DEV Community: Martin Oehlert

Human Interaction and External Events: Approval Workflows

Martin Oehlert — Fri, 03 Jul 2026 05:59:36 +0000

An expense report needs a manager's sign-off before the reimbursement goes out, and that manager might click approve in five minutes or come back from a trip in five days. The question Parts 1 and 2 never had to answer is how the workflow waits that long: a chain or a fan-out runs to completion in seconds, but an approval step has to suspend on a person and stay suspended without holding a thread or billing you for the idle time in between. Durable Functions answers the waiting half with a single await that costs no compute while it is parked. The half most guides skip is the other one: the runtime hands you an instance ID when the workflow starts, and finding that one paused instance again when the approval finally arrives is your code's job, not the platform's.

WaitForExternalEvent pattern

The mechanic at the center of every approval workflow is one line: await context.WaitForExternalEvent<T>(eventName). It suspends the orchestration until something outside the function raises an event with that name, and the typed payload it returns carries whatever the approver decided.

Every code sample below is from the companion sample (isolated worker, .NET 10). Here is the expense-approval orchestrator: it parks on the wait, then hands the decision to an activity that settles or rejects the report.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;

public record ExpenseReport(string ReportId, string Employee, decimal Amount, string Category);
public record ApprovalDecision(string DecisionId, bool Approved, string Approver, string? Note);
public record SettlementInput(ExpenseReport Report, ApprovalDecision Decision);

public static class ExpenseApprovalOrchestrator
{
    [Function(nameof(ExpenseApprovalOrchestrator))]
    public static async Task<string> Run(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var report = context.GetInput<ExpenseReport>()!;

        // Suspends here until an "ApprovalDecision" event is raised for this instance.
        // No thread is held and no compute is billed while the orchestration waits.
        ApprovalDecision decision =
            await context.WaitForExternalEvent<ApprovalDecision>("ApprovalDecision");

        return await context.CallActivityAsync<string>(
            nameof(SettleExpenseActivity), new SettlementInput(report, decision));
    }
}

The WaitForExternalEvent<ApprovalDecision>("ApprovalDecision") call is the whole pause. When the orchestrator reaches it, the runtime checkpoints the instance and unloads it; execution does not resume until an event named ApprovalDecision is raised against this instance ID, at which point the raised JSON is deserialized into an ApprovalDecision and the await returns it. The first argument is the event name, the contract both ends agree on, and matching is case-insensitive: a wait on "ApprovalDecision" is satisfied by an event raised as "approvaldecision". The type argument is the payload shape; if the raised JSON cannot be converted to it, the wait throws rather than returning a half-filled object.

The activity is an ordinary function that acts on the decision.

public static class SettleExpenseActivity
{
    [Function(nameof(SettleExpenseActivity))]
    public static string Run([ActivityTrigger] SettlementInput input)
    {
        var (report, decision) = input;
        if (!decision.Approved)
            return $"Report {report.ReportId} rejected by {decision.Approver}.";

        // Real work belongs here: queue the reimbursement, post to the ledger, notify the employee.
        return $"Report {report.ReportId} approved by {decision.Approver}; {report.Amount:C} scheduled for payment.";
    }
}

What makes this safe to wait on for days is that the suspension costs no compute. Once the orchestrator yields at the wait, there is no thread blocked, no instance kept warm, nothing to bill. On the Consumption and Flex plans you pay for actual execution, not idle wait time, so an approval parked for a week is free until the event arrives. The wait is also replay-safe in exactly the sense Part 1 set up: the pending event is part of the orchestration's durable state, so the worker can be stopped, scaled in, or recycled, and the instance is reawakened when the event shows up. An event that arrives early is not a problem either; if it is raised before the orchestrator has reached the wait, it is buffered in the instance state and dispatched the moment the wait is reached, so a fast approver who beats the orchestration to the wait line does not lose their decision.

One honest gotcha to design for up front: event delivery on the Azure Storage backend is at-least-once, so a restart or scale event can deliver the same approval twice. That is why the payload here carries a DecisionId. If the downstream activity is not naturally idempotent, dedupe on that ID so a duplicate delivery does not pay the same expense report twice. (The MSSQL provider consumes events transactionally and does not produce duplicates, but coding for at-least-once keeps the orchestrator portable across backends.)

This wait is indefinite: nothing here ever gives up. A real approval workflow needs a deadline so a report that no one ever touches does not sit parked forever, and bounding the wait with a durable timer is the next section.

Approval endpoint design

The orchestrator only knows how to wait. Two HTTP endpoints surround it: one to start the workflow and one to deliver the approver's answer. The start endpoint is the async HTTP pattern from Part 2, schedule the orchestration and hand back a status URL without blocking.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.DurableTask.Client;

public static class StartExpenseApprovalClient
{
    [Function(nameof(StartExpenseApprovalClient))]
    public static async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "expenses")]
            HttpRequestData req,
        [DurableClient] DurableTaskClient client)
    {
        ExpenseReport report = await req.ReadFromJsonAsync<ExpenseReport>()
            ?? throw new InvalidOperationException("Expense report body is required.");

        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
            nameof(ExpenseApprovalOrchestrator), report);

        // 202 + management URLs; the orchestration is now parked on its WaitForExternalEvent.
        return await client.CreateCheckStatusResponseAsync(req, instanceId);
    }
}

ScheduleNewOrchestrationInstanceAsync enqueues the orchestration and returns its instance ID without waiting for it to run, and CreateCheckStatusResponseAsync builds the HTTP 202 response: a Location header pointing at the status-query endpoint and a JSON body of management URLs for the instance. By the time the caller has that 202, the orchestration is already parked on its WaitForExternalEvent. Hold on to that returned instanceId; it is the only handle that reaches the parked instance, and the approval endpoint is useless without it.

The approval endpoint is the other half. It reads the manager's decision and raises the event the orchestrator is blocked on.

public record ApprovalRequest(bool Approved, string Approver, string? Note);

public static class SubmitApprovalClient
{
    [Function(nameof(SubmitApprovalClient))]
    public static async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "expenses/{instanceId}/decision")]
            HttpRequestData req,
        string instanceId,
        [DurableClient] DurableTaskClient client)
    {
        ApprovalRequest body = await req.ReadFromJsonAsync<ApprovalRequest>()
            ?? throw new InvalidOperationException("Approval body is required.");

        var decision = new ApprovalDecision(
            DecisionId: Guid.NewGuid().ToString("N"),
            Approved: body.Approved,
            Approver: body.Approver,
            Note: body.Note);

        // Raises the event the orchestrator is waiting on. Returns when the event is
        // enqueued, not when the orchestrator has consumed it.
        await client.RaiseEventAsync(instanceId, "ApprovalDecision", decision);

        return await client.CreateCheckStatusResponseAsync(req, instanceId);
    }
}

RaiseEventAsync(instanceId, "ApprovalDecision", decision) is the mirror image of the wait. The event name has to match the orchestrator's wait name (again, case-insensitively), and the decision object is JSON-serialized and deserialized into the orchestrator's ApprovalDecision on the other side. The returned task completes when the event is enqueued, not when the orchestrator wakes up and consumes it, so a 202 here means "your decision is on its way," not "the report is settled." The caller polls the status URL to see the workflow reach Completed. Generating the DecisionId server-side is what makes the earlier dedupe work: it gives every raised decision a stable identity even if the platform delivers it twice.

There are two ways to raise this event, and the choice is the reason this endpoint exists at all. The 202 body from the start call already contains a sendEventPostUri, the built-in raise-event API: a caller can POST the decision straight to .../instances/{instanceId}/raiseEvent/ApprovalDecision with no code from you. It is the quickest path, and it returns useful status codes (404 for an unknown instance, 410 for one that already finished). What it does not give you is a place to put your own concerns. The custom endpoint above exists so you can own the route, authentication, validation, and audit: check that this approver is allowed to sign off this report, record who decided and when, reject a malformed body before it ever reaches the orchestration. If none of that matters for your case, the built-in webhook is less to maintain.

The honest gotcha lives in the failure mode of the SDK call. A bare RaiseEventAsync to a completed or non-existent instance is silently discarded: no exception, no error, nothing. Raise ApprovalDecision against a stale or mistyped instance ID and the call returns happily while the event evaporates, and the approver sees a success they did not get. If you need to tell an approver that the workflow they are signing off no longer exists, pre-check with GetInstanceAsync and inspect the runtime status before raising, or use the built-in HTTP API and surface its 404 and 410 to the caller. The silent path is convenient until the instance ID is wrong.

Which raises the question this endpoint quietly assumes away: it takes instanceId from the route as if the caller already knows it. Where that ID comes from, how the approval link in the manager's email ends up carrying the right one, and how you avoid losing it, is its own problem, and the section on instance ID storage is where it gets solved.

Timeout and escalation

A wait that never gives up is a workflow you cannot operate. The previous section left the orchestration parked on WaitForExternalEvent with no exit; a report that no manager ever touches stays Running until someone terminates it by hand. The fix is to race the event against a durable timer and let whichever finishes first decide the outcome.

Start the timer and the wait, then await Task.WhenAny on the pair. The orchestration wakes on the first of the two to complete.

public static class ExpenseApprovalOrchestrator
{
    [Function(nameof(ExpenseApprovalOrchestrator))]
    public static async Task<string> Run(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var report = context.GetInput<ExpenseReport>()!;

        // Deadline comes off the orchestration clock, NOT DateTime.UtcNow. Part 1's
        // determinism rule: every replay must compute the same instant, and
        // CurrentUtcDateTime is frozen to the original execution time on replay.
        DateTime deadline = context.CurrentUtcDateTime.AddDays(3);

        using var cts = new CancellationTokenSource();
        Task<ApprovalDecision> approvalTask =
            context.WaitForExternalEvent<ApprovalDecision>("ApprovalDecision");
        Task timeoutTask = context.CreateTimer(deadline, cts.Token);

        Task winner = await Task.WhenAny(approvalTask, timeoutTask);

        if (winner == approvalTask)
        {
            // The approval landed first. Cancel the timer before moving on.
            cts.Cancel();
            return await context.CallActivityAsync<string>(
                nameof(SettleExpenseActivity),
                new SettlementInput(report, approvalTask.Result));
        }

        // The timer won: nobody decided in time. Fail closed by auto-rejecting.
        var timedOut = new ApprovalDecision(
            DecisionId: $"timeout-{report.ReportId}",
            Approved: false,
            Approver: "system (timeout)",
            Note: $"No decision by {deadline:o}.");
        return await context.CallActivityAsync<string>(
            nameof(SettleExpenseActivity), new SettlementInput(report, timedOut));
    }
}

Two details carry the weight here. The first is the deadline source. context.CurrentUtcDateTime is the replay-safe clock from Part 1: on the first execution it is the real time, and on every replay after a checkpoint it returns that same original value, so AddDays(3) resolves to one fixed instant no matter how many times the orchestrator re-runs. Use DateTime.UtcNow instead and the deadline drifts forward on every replay, which breaks determinism and can move the timer past where it should have fired.

The second is the cts.Cancel() on the approval branch, and it is easy to read as optional cleanup when it is not. CreateTimer registers a durable timer in the instance state, and the framework will not let an orchestration reach Completed while a timer it created is still outstanding. Skip the cancel and your approved report settles its activity, then sits in Running for the rest of the three days until the abandoned timer finally fires. Cancelling the token does not abort anything in flight; it tells the runtime to drop the pending timer so the orchestrator can finish now. The using on the CancellationTokenSource disposes it when the method exits.

Fail-closed is a choice, not a rule. Auto-rejecting on timeout is the conservative default: an expense nobody approved should not be paid. The richer variant is to escalate rather than reject. Instead of returning, the timeout branch notifies a second approver (in the expense case, the manager's manager) and waits again with a fresh timer.

// Escalation variant for the timeout branch: re-notify, then wait once more.
await context.CallActivityAsync(nameof(NotifyEscalationApproverActivity), report);

using var escalationCts = new CancellationTokenSource();
Task<ApprovalDecision> escalatedApproval =
    context.WaitForExternalEvent<ApprovalDecision>("ApprovalDecision");
Task escalationTimeout =
    context.CreateTimer(context.CurrentUtcDateTime.AddDays(2), escalationCts.Token);

if (await Task.WhenAny(escalatedApproval, escalationTimeout) == escalatedApproval)
{
    escalationCts.Cancel();
    return await context.CallActivityAsync<string>(
        nameof(SettleExpenseActivity),
        new SettlementInput(report, escalatedApproval.Result));
}
// Still nothing after the second window: now fail closed.

Each escalation round is the same race with a new deadline and a new CancellationTokenSource, so the same two rules apply every time: derive the deadline from CurrentUtcDateTime, cancel the timer when the event wins. You can wrap the round in a loop to escalate up a chain of approvers, but give it a hard ceiling; an unbounded escalation loop is the indefinite wait you just removed, wearing a different hat.

Instance ID storage patterns

The approval endpoint took instanceId straight from its route, as if the caller already had it. The start endpoint, meanwhile, returned that ID inside a 202 and then dropped it. So when the manager opens an email three days later and clicks approve, what fills in the {instanceId} segment of expenses/{instanceId}/decision? This is the half the intro flagged: Durable Functions hands you the instance ID at start time and keeps no index from a business entity to its instance ID. Mapping report R-2048 back to the orchestration that is waiting on it is your code's job, and there are three ways to do it.

Option 1: an external store keyed by the business entity. Write a row at start time (ReportId to instanceId) into whatever database or lookup service you already run, then read it back in the approval endpoint. This is the production default. It is authoritative and queryable, it supports many runs mapping to one entity and full history, and it survives instance purging. The cost is that you now own a second piece of state: an extra write on start, an extra read on approval, and the consistency between that row and the orchestration is yours to keep (make the write idempotent or transactional with the start so you cannot end up with a row pointing at an instance that never scheduled, or an instance with no row).

Option 2: make the instance ID the business key, and store nothing. ScheduleNewOrchestrationInstanceAsync lets you supply the ID instead of taking an autogenerated GUID, via StartOrchestrationOptions.InstanceId. If the ID is the report key, the approval endpoint reconstructs it from the route with no lookup at all.

string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
    nameof(ExpenseApprovalOrchestrator),
    report,
    new StartOrchestrationOptions { InstanceId = $"expense-{report.ReportId}" });

Now the email link is just expenses/expense-{ReportId}/decision, built from data you already have, and there is no table to keep in sync. The constraints are real, though, and the runtime enforces them unevenly across storage providers, so honor them regardless: the ID must be unique within the task hub, 1 to 100 characters, must not start with @, and must not contain /, \, #, ?, or control characters. Raw GUIDs are fine; emails and file paths usually need encoding first. The mapping is strictly one-to-one, so this fits short, naturally unique, single-run keys and not much else. A report ID like expense-R-2048 qualifies; a customer who can file many reports does not.

Option 2 also inherits a gotcha worth stating plainly: scheduling an instance ID that already exists is not a safe atomic create-if-absent. The documented pattern is check-then-start (call GetInstanceAsync, inspect RuntimeStatus, and start only if the instance is missing or in a terminal state), and Microsoft flags a concurrency race even then: two requests for the same key can both pass the check and both report success while only one orchestration actually runs. If a duplicate submit must never double-schedule, you need a lock outside Durable Functions, which starts to erode the "store nothing" advantage.

Option 3: a Durable Entity as a registry. Entities are supported in the .NET isolated worker (the "not in isolated" caveat you may have read refers to in-orchestration critical sections, not entities), their operations run serially so there is no intra-entity race, and the index stays inside Durable Functions instead of a separate database. Treat this as viable but unproven: no official guidance endorses an entity as the business-key index, entities favor durability over latency so client reads can be stale, and routing every lookup through one hot registry entity serializes all traffic into a throughput bottleneck. Reach for it only if you have a specific reason to avoid an external store.

One temptation to rule out: the query APIs are not a reverse lookup. GetInstanceAsync needs the ID you are trying to find. GetAllInstancesAsync(OrchestrationQuery) filters only on runtime status, time range, and orchestration name, with no predicate for an arbitrary business key, so finding R-2048 that way means scanning every instance client-side, an O(n) walk that degrades as history grows and breaks once completed instances are purged. Custom status (SetCustomStatus) is for surfacing progress and caps at 16 KB; tags are queryable only in the scheduler dashboard, not from code. None of them is a point lookup. A business key to instance ID mapping always comes back to an app-owned index (option 1) or a derivable ID (option 2).

For the expense workflow the call is short. If a report ID is already a clean single-run key, option 2 removes a whole moving part: the email link encodes the ID and there is nothing to persist or reconcile. The moment you need many approvals per report, audit history, or a key that does not survive the ID character rules, option 1's extra row pays for itself.

Wrapping up

The pause is the easy half. WaitForExternalEvent suspends for days on a single await and bills you nothing while it waits, and a CreateTimer race keeps that wait from becoming a leak. The half that decides whether this works in production is the one most walkthroughs skip: the instance ID is a handle the platform hands you once and never indexes, so reuniting a parked workflow with the human who finally answers it is a design decision you make on purpose, at start time. Get that wrong and the approver clicks a link that raises an event into the void.

So make the call deliberately on your next approval workflow: do you persist the instance ID in an external table keyed by the business entity, or derive it from the business key so there is nothing to store?

Fan-Out/Fan-In and the Async HTTP Pattern

Martin Oehlert — Fri, 26 Jun 2026 05:00:00 +0000

You have 500 order line items to process and no ordering dependency between them, so the question is why the workflow takes as long as 500 activities run back to back when nothing forces them to. The chaining pattern from Part 1 awaits each activity before scheduling the next, which is exactly right when step two needs step one's output and exactly wasteful when the items are independent. The fix is fan-out/fan-in: schedule all the activities at once, then aggregate the results, and the only real trick is doing it in a way that survives the orchestrator replaying. There is also a one-character version of this code that compiles, runs, and silently throws the parallelism away, which is the bug this article spends the most time on.

When sequential processing isn't enough

Chaining is the pattern you reach for when the steps form a line: validate the order, then create it, then send the confirmation, each one feeding the next. The await between steps is load-bearing there, because CreateOrderActivity genuinely cannot start until ValidateOrderActivity has returned. That dependency is what makes the sequence correct.

Now change the shape of the work. A batch order arrives with 500 line items, and each one needs the same per-item processing: check stock, price it, reserve inventory. No line item depends on any other. If you write that as a chain, awaiting each item's activity before scheduling the next, the total wall-clock time is the sum of all 500 activities. At a rough sequential ceiling of about 5 activities per second on a single instance, that batch takes roughly a minute and a half, and every second of it is one item waiting on the item before it for no reason.

The independence is the whole point. When the items have no ordering relationship, the latency you actually care about is not the sum of the activities but the slowest single one, because there is nothing stopping them from running at the same time. Fan out across the available workers and the same batch finishes in the time of its longest item, plus a little aggregation overhead. The documented fan-out throughput target is around 100 activities per second per instance, an order of magnitude over the sequential figure, and that gap is entirely the difference between running the work in series and running it in parallel.

Fan-out/fan-in is the orchestration pattern for that situation: fan out by scheduling many activities at once, fan in by waiting for all of them and collecting the results. The replay engine from Part 1 is what makes it safe, and the next section shows the exact shape.

Fan-out/fan-in with Task.WhenAll

The shape has two halves. Fan-out means projecting your inputs into activity calls and collecting the tasks without awaiting any of them. Fan-in means a single await Task.WhenAll(tasks) that completes once every activity has finished, handing you the results.

Every code sample below is from the companion sample (isolated worker, .NET 10). Here is the batch processor as an orchestrator, with an aggregation step at the end.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;

public record OrderItem(string Sku, int Quantity);
public record OrderResult(string Sku, bool Reserved, decimal LineTotal);
public record BatchSummary(int Processed, int Reserved, decimal Total);

public static class ProcessBatchOrchestrator
{
    [Function(nameof(ProcessBatchOrchestrator))]
    public static async Task<BatchSummary> Run(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var items = context.GetInput<OrderItem[]>()!;

        // Fan-out: schedule every item at once, collect the tasks unawaited.
        Task<OrderResult>[] tasks =
            [.. items.Select(item => context.CallActivityAsync<OrderResult>(
                nameof(ProcessItemActivity), item))];

        // Fan-in: one await blocks until all of them complete.
        OrderResult[] results = await Task.WhenAll(tasks);

        // Optional: hand the collected results to a final aggregation activity.
        return await context.CallActivityAsync<BatchSummary>(
            nameof(SummarizeBatchActivity), results);
    }
}

The fan-out is the collection expression. items.Select(...) projects each OrderItem into a CallActivityAsync<OrderResult> call, and because nothing awaits those calls, each one schedules an activity and returns its Task<OrderResult> immediately. The [.. ...] spread materializes them into a Task<OrderResult>[]. After that line, all 500 activities are scheduled; none has been waited on.

await Task.WhenAll(tasks) is the fan-in. It returns a single task that completes only when every task in the array has completed, and its result is an OrderResult[]. The element order matches the order of the tasks array, not the order the activities happened to finish in, so results[0] is always the result for items[0] regardless of which line item processed fastest. That positional guarantee is standard Task.WhenAll<TResult> behavior, and it is why you can return the array directly without sorting or correlating anything back to its input.

The activity itself is an ordinary function doing the per-item work.

public static class ProcessItemActivity
{
    [Function(nameof(ProcessItemActivity))]
    public static OrderResult Run([ActivityTrigger] OrderItem item)
    {
        // Real work and I/O belong here: check stock, price, reserve inventory.
        bool reserved = item.Quantity > 0;
        decimal lineTotal = item.Quantity * 9.99m;
        return new OrderResult(item.Sku, reserved, lineTotal);
    }
}

Task.WhenAll is not one of the nondeterministic APIs banned inside an orchestrator. It is replay-safe, and the reason traces straight back to Part 1's replay engine. The durable calls it aggregates are the replay-checkpointed operations: the runtime records each scheduled CallActivityAsync in the History table the moment the orchestrator yields, and records each result as it arrives. On a replay the orchestrator reaches the same fan-out line, the framework sees those activities already scheduled (and any already completed), and reconstructs the same task array from history rather than re-running the work. The whole parallel batch therefore survives a host recycle the same way a chain does: the activities run across multiple workers concurrently, and the end-to-end execution is resilient to the orchestrator being unloaded and replayed.

One behavior to know before you ship this. When several activities fail, await Task.WhenAll(tasks) throws only the first exception, even though more than one task faulted. If you need to see every failure (to log all of them, or decide based on how many failed) inspect the Exception property on the task that Task.WhenAll returns, which holds the full AggregateException with one inner exception per faulted activity.

The loop mistake (and the fix)

The previous section showed the correct shape. This section is about the version that looks just as correct, compiles cleanly, runs without error, and quietly runs everything in series anyway. It is the most common fan-out bug, and it is worth being able to spot in a code review on sight, because nothing else will flag it for you.

Here is the broken orchestrator. A reviewer skimming it sees a loop over the items, an activity call per item, and a list of results. It reads like a fan-out.

// BROKEN: awaiting inside the loop runs the activities one after another.
[Function(nameof(ProcessBatchOrchestrator))]
public static async Task<OrderResult[]> Run(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var items = context.GetInput<OrderItem[]>()!;
    var results = new List<OrderResult>();
    foreach (var item in items)
        results.Add(await context.CallActivityAsync<OrderResult>(
            nameof(ProcessItemActivity), item));   // awaits before scheduling the next
    return [.. results];
}

The await is in the wrong place. Each iteration calls CallActivityAsync, then await suspends the orchestrator until that one activity returns, and only after the result is added to the list does the loop come back around to schedule the next item. So the activities are scheduled one at a time, each waiting on the one before it. This is the chaining pattern wearing a loop, and it has the chaining pattern's latency: the sum of all 500 activities, back at roughly 5 per second. There is no compiler warning, no runtime exception, no log line that looks wrong. The only symptom is that a batch that should take a couple of seconds takes a minute and a half, and you usually only notice once the batch sizes grow in production.

The fix is to move the await out of the loop. Schedule everything first, collect the tasks, then fan in with a single Task.WhenAll.

// FIXED: collect every task first, then fan in with one Task.WhenAll.
[Function(nameof(ProcessBatchOrchestrator))]
public static async Task<OrderResult[]> Run(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var items = context.GetInput<OrderItem[]>()!;
    Task<OrderResult>[] tasks =
        [.. items.Select(item => context.CallActivityAsync<OrderResult>(
            nameof(ProcessItemActivity), item))];   // scheduled, not awaited
    return await Task.WhenAll(tasks);                // all run in parallel
}

The difference is whether await sits on each individual call or once on the whole array. In the broken version every CallActivityAsync is awaited the instant it is made, which serializes the schedule-and-wait. In the fixed version the Select schedules all of them without awaiting any, and the single await Task.WhenAll(tasks) is the only suspension point, so the activities are in flight together and the worker fans them out across the pool. Same activity, same input, same result array (Task.WhenAll preserves the order of the tasks array, so you can return it directly), and at batch scale the difference is roughly 100 activities per second instead of 5.

The review heuristic: if you see await on a durable call inside a foreach or for loop, stop and ask whether those iterations actually depend on each other. If iteration N needs iteration N-1's output, awaiting in the loop is correct, that is a chain. If they are independent, the await belongs on a Task.WhenAll after the loop, and leaving it inside is the silent serialization trap.

The async HTTP pattern

A 500-item batch that fans out to activities can run for a minute and a half, and no HTTP client should be holding a socket open that long. Browsers, load balancers, and API gateways all time out well before that, so a client function that started the orchestration and blocked on its result would fail the caller before the batch even finished. The async HTTP pattern solves this by separating starting the work from collecting its result: the HTTP trigger kicks off the orchestration and returns immediately with a set of URLs the caller can poll.

Here is the client function that starts ProcessBatchOrchestrator and hands the caller back a status endpoint.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.DurableTask.Client;

public static class StartBatchClient
{
    [Function(nameof(StartBatchClient))]
    public static async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "batches")]
            HttpRequestData req,
        [DurableClient] DurableTaskClient client)
    {
        OrderItem[] items = await req.ReadFromJsonAsync<OrderItem[]>() ?? [];

        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
            nameof(ProcessBatchOrchestrator), items);

        // 202 Accepted + Location + the management URLs, without blocking on the result.
        return await client.CreateCheckStatusResponseAsync(req, instanceId);
    }
}

ScheduleNewOrchestrationInstanceAsync enqueues the orchestration and returns its instance id without waiting for it to run. CreateCheckStatusResponseAsync then builds the response: HTTP 202 Accepted, a Location header pointing at the status-query endpoint, and a Retry-After header (10 seconds by default) telling the caller how long to wait before polling again. Prefer the awaited CreateCheckStatusResponseAsync over the synchronous CreateCheckStatusResponse: under the ASP.NET Core integration the synchronous form can throw InvalidOperationException ("Synchronous operations are disallowed"), which is why the async overload exists.

The JSON body carries the management URLs for the instance:

{
  "id": "7f3c1e9a4b8d4f0e9c2a6b5d8e1f0a3c",
  "statusQueryGetUri": "https://.../runtime/webhooks/durabletask/instances/7f3c...?...",
  "sendEventPostUri": "https://.../instances/7f3c.../raiseEvent/{eventName}?...",
  "terminatePostUri": "https://.../instances/7f3c.../terminate?reason={text}&...",
  "suspendPostUri": "https://.../instances/7f3c.../suspend?reason={text}&...",
  "resumePostUri": "https://.../instances/7f3c.../resume?reason={text}&...",
  "purgeHistoryDeleteUri": "https://.../instances/7f3c...?..."
}

statusQueryGetUri is the one the caller polls (it is the same URL as the Location header); the others handle raising an external event, terminating, suspending, resuming, and purging the instance's history. A preview rewindPostUri shows up too on supported plans.

From the caller's side it is a poll loop against statusQueryGetUri. While the instance is still running the status endpoint returns 202, with its own Location header pointing back at itself; once the instance reaches a terminal state it returns 200 with the full status body, and the body's output field carries the orchestration's return value. The runtimeStatus field tells you which state you landed in: Running, Pending, Failed, Canceled, Terminated, Completed, or Suspended.

A curl-style poll honoring Retry-After is the whole client protocol:

using HttpClient http = new();
HttpResponseMessage start = await http.PostAsJsonAsync(
    "https://.../api/batches", items);

// 202 came back; Location is the status-query URL.
Uri statusUri = start.Headers.Location!;

while (true)
{
    HttpResponseMessage status = await http.GetAsync(statusUri);
    if (status.StatusCode == HttpStatusCode.OK)
    {
        BatchSummary? summary = await status.Content
            .ReadFromJsonAsync<StatusResponse>() is { Output: var o } ? o : null;
        // runtimeStatus == "Completed"; the result is in the body's output field.
        break;
    }

    // 202: still running. Wait the Retry-After the server asked for.
    TimeSpan wait = status.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(10);
    await Task.Delay(wait);
}

If your caller can tolerate a short synchronous wait (a small batch that usually finishes in a second or two), WaitForCompletionOrCreateCheckStatusResponseAsync collapses the round trip: it waits for the instance to complete and returns its output with a 200, and if the wait elapses first it falls back to the same 202 + management-URL payload. The isolated-worker signature is worth a careful read, because it differs from the in-process one: it takes a retryInterval for the internal poll cadence and a CancellationToken that bounds the overall wait, but there is no timeout parameter. You cap the wait by cancelling the token, not by passing a TimeSpan.

Memory and concurrency limits

Two things bite at batch scale that never show up on a three-item demo: where all those activity results go, and how parallel the fan-out actually runs.

Start with memory. Every activity output is serialized into the orchestration's history in the <TaskHubName>History table, and Part 1's replay engine loads that full history into memory each time the orchestrator replays. With a 500-wide fan-out, the fan-in array is 500 serialized results sitting in history and getting rehydrated on every replay. If each result is small that is fine; if each activity returns a multi-megabyte payload, history balloons. Past 45 KB serialized, a result spills over to a <taskhub>-largemessages blob container automatically (the underlying Azure Queue message hard cap is 64 KB, and the 45 KB threshold leaves headroom for the compressed form). That spillover is correctness-preserving, but it is not free: it costs CPU and IO for the compress-and-round-trip, and the rehydrated payloads still bloat replay memory.

The fix is to return a reference, not the bytes. Have the activity write the heavy payload to blob storage and return a small id the fan-in can carry cheaply.

// BROKEN: the multi-MB image is serialized into history on fan-in.
[Function(nameof(RenderPageActivity))]
public static RenderedPage Run([ActivityTrigger] int page)
{
    byte[] image = Renderer.ToPng(page);     // multi-MB payload
    return new RenderedPage(page, image);    // every byte lands in history
}

// FIXED: write the payload to blob storage, return a small reference.
[Function(nameof(RenderPageActivity))]
public static async Task<PageRef> Run([ActivityTrigger] int page)
{
    byte[] image = Renderer.ToPng(page);
    string blobName = await Blobs.UploadAsync($"pages/{page}.png", image);
    return new PageRef(page, blobName);      // history carries a reference, not the bytes
}

Whatever needs the bytes later reads them back from blob storage by name. The history stays small, replay stays fast, and you never go near the spillover threshold.

Now concurrency. Fan-out is not unbounded parallelism. Scheduling 500 activities at once does not mean 500 run at once; the host caps how many activities execute concurrently per instance through maxConcurrentActivityFunctions, which defaults to 10 on the Consumption plan (10x the processor count on Dedicated and Premium). Orchestrators have their own ceiling, maxConcurrentOrchestratorFunctions, defaulting to 5. Both live under extensions.durableTask in host.json:

{
  "extensions": {
    "durableTask": {
      "maxConcurrentActivityFunctions": 10,
      "maxConcurrentOrchestratorFunctions": 5
    }
  }
}

Both limits are per-instance, so scale-out multiplies them: ten workers at the default give you up to 100 activities in flight. The surplus past the concurrency limit does not fail, it queues, and the runtime drains it as slots free up. So a 500-wide fan-out on a single instance runs about 10 at a time with the rest waiting their turn, and the batch is only as parallel as your concurrency setting times your worker count allows. Size the fan-out against that ceiling rather than assuming the width you scheduled is the width that runs.

Closing

The whole pattern turns on where one await sits. Move it off the individual CallActivityAsync calls and onto a single Task.WhenAll, and the same orchestrator that ran 500 items in series now runs them in parallel, replay-safe, across every worker the platform gives you. The async HTTP pattern lets a caller start that batch and walk away with a status URL instead of a held-open socket, and the memory and concurrency caps are the guardrails that keep a wide fan-out from quietly bloating history or pretending to be more parallel than it is.

Part 3 picks up the other half of orchestration: workflows that pause and wait on something outside the function, like a human approval or an external event, without burning compute while they wait.

Do you cap your fan-out width with a host.json concurrency limit, or let the platform scale it and size the batch to fit?

Intro to Durable Functions: Orchestrations and the Chaining Pattern

Martin Oehlert — Fri, 19 Jun 2026 06:01:50 +0000

An order comes in, and you need to validate it, create it, then send a confirmation, three steps that have to run in order and survive a crash halfway through. A single Azure Function can't do that, because the moment it returns it forgets everything, so the usual fix is a chain of queue-triggered functions wired together with a correlation ID, a status table, and your own retry logic. That hand-rolled state machine is exactly what Durable Functions replaces, and the price of admission is learning to write an orchestrator: normal-looking C# that the runtime is allowed to run more than once.

Why a stateless function can't run a workflow

A plain Azure Function is a single invocation. It receives a trigger, runs, returns, and the worker that ran it can be recycled the instant it finishes. Nothing in the function body survives to the next invocation: no local variables, no "where was I" pointer, no record that step two of a three-step process already succeeded. That design is what makes Functions cheap to scale, and it's the right model for the bulk of event handlers you write.

It stops being enough the moment one logical unit of work spans more than one step. Take the order example: validate the request, create the order record, send a confirmation. You want those to run in sequence, you want the second step to use the output of the first, and you want the whole thing to pick up where it left off if the host restarts between steps. None of that is possible inside one function, so the standard pattern is to split each step into its own queue-triggered function and pass a message down the chain.

That works, but look at what you end up owning. You need a correlation ID so you can tell which messages belong to the same order. You need a status table so you can answer "is order 4815 done yet" and so a retry doesn't redo a step that already completed. You need poison-queue handling, timeout logic, and some way to fan results back together if any step branches. You have hand-built a state machine, and state machines spread across five queues are where the 2 a.m. pages come from.

Durable Functions takes over the state. It records every step your workflow completes in durable storage, and it reconstructs your workflow's position from that record after any interruption. You write the sequence as ordinary C# with await between the steps; the runtime makes the sequence survive crashes, scale-ins, and host upgrades. The correlation ID, the status table, and the retry bookkeeping all move from your code into the framework.

The three roles: orchestrator, activity, client

Durable Functions splits a workflow into three kinds of function, each identified by a trigger or binding type. Keeping them straight is most of the battle when you're starting out, because the rules about what code is legal where depend entirely on which role you're in.

The orchestrator is the workflow itself. It's a function marked with the [OrchestrationTrigger] binding, and its job is to coordinate: call this step, wait for the result, decide what to call next. It contains the control flow (if, loops, sequencing) but does no real work of its own. The orchestrator is the one role with a hard constraint attached. Its body can be re-executed many times over the life of a single workflow instance, so the code in it must be deterministic. That single fact (the orchestrator replays) is what the rest of this series keeps coming back to; the replay mechanics and the exact list of rules are covered later in this article.

An activity is where the actual work happens. It's a function marked with [ActivityTrigger], and it's the only one of the three roles allowed to touch the outside world: database writes, HTTP calls, sending email, reading a blob. Activities can bind directly to their input type, so an activity that validates an order can take an OrderRequest parameter and nothing else. The guarantee Durable Functions gives you on activities is at-least-once execution, and that has a real consequence. An activity can run more than once for the same logical step (after a transient failure and retry, for instance), so activity logic should be idempotent. Sending a confirmation email twice because the worker died after sending but before recording success is the kind of bug this guarantee invites if you're not careful.

The client (often called the starter) is the entry point that kicks a workflow off and lets you query it. In the isolated worker model the client is the injected DurableTaskClient, supplied through the [DurableClient] binding on a normal trigger such as an HTTP function. It is not something you call from inside an orchestrator; it lives in regular functions that start instances with ScheduleNewOrchestrationInstanceAsync and hand back a status response the caller can poll.

Behind all three sits the task hub: the set of Azure Storage resources (queues, tables, and a couple of blob containers) that the default storage provider creates in your function app's storage account to hold the workflow's messages and history. You don't provision it or write to it directly. It's enough to know it exists and that it's where your workflow's durable state actually lives; the history table inside it is the star of the replay section below.

The chaining pattern

Function chaining is the simplest orchestration and the one you'll reach for most. You run a sequence of activities in order, where each step's output feeds the next. Here is the order-processing workflow as an orchestrator.

using Microsoft.Azure.Functions.Worker;
using Microsoft.DurableTask;

public record OrderRequest(string CustomerId, string Sku, int Quantity);

public static class OrderOrchestrator
{
    [Function(nameof(OrderOrchestrator))]
    public static async Task<string> RunOrchestrator(
        [OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var order = context.GetInput<OrderRequest>()!;

        var validated = await context.CallActivityAsync<bool>(
            nameof(ValidateOrderActivity), order);
        if (!validated)
            return "Order validation failed";

        var orderId = await context.CallActivityAsync<string>(
            nameof(CreateOrderActivity), order);

        await context.CallActivityAsync(
            nameof(SendConfirmationActivity), orderId);

        return orderId;
    }
}

Read it top to bottom and it's the sequence from the opening, written as plain C#. context.GetInput<OrderRequest>() pulls the input the client passed when it started the instance; the ! is there because the input is typed as nullable and you know this orchestrator always gets one. Each await context.CallActivityAsync(...) schedules an activity and waits for its result before moving on, which is what gives you the chain: validated gates whether the order is created, and orderId (the output of CreateOrderActivity) becomes the input to SendConfirmationActivity.

The call comes in two shapes. When an activity returns a value you use the generic CallActivityAsync<TResult>, which gives you back a Task<TResult>: CallActivityAsync<bool> for the validation result, CallActivityAsync<string> for the new order ID. When an activity is fire-the-step with nothing to return, you use the non-generic CallActivityAsync, which returns a plain Task; that's the confirmation send. The first argument is the activity name as a TaskName, and since there's an implicit conversion from string, nameof(ValidateOrderActivity) works directly and keeps the name refactor-safe.

The activity is an ordinary function that does the real work. This is where I/O is allowed, so it's where validation against your database or rules engine actually happens.

public static class ValidateOrderActivity
{
    [Function(nameof(ValidateOrderActivity))]
    public static bool Run([ActivityTrigger] OrderRequest order)
    {
        // Real work and I/O belong here, never in the orchestrator:
        // check inventory, validate the customer, hit the database.
        return order.Quantity > 0 && !string.IsNullOrWhiteSpace(order.Sku);
    }
}

The activity binds straight to OrderRequest, the same type the orchestrator passed as input, so there's no manual deserialization. Keep in mind the at-least-once guarantee from earlier. If ValidateOrderActivity did something with side effects, you'd want running it twice to be safe. Pure validation like this is naturally idempotent, which is one reason it's a good first step in the chain.

Something has to start the workflow. That's the client, here an HTTP-triggered function that schedules a new instance and returns a status response the caller can poll.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.DurableTask.Client;

public static class OrderClient
{
    [Function(nameof(StartOrder))]
    public static async Task<HttpResponseData> StartOrder(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req,
        [DurableClient] DurableTaskClient client)
    {
        var order = await req.ReadFromJsonAsync<OrderRequest>();

        string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
            nameof(OrderOrchestrator), order);

        return client.CreateCheckStatusResponse(req, instanceId);
    }
}

ScheduleNewOrchestrationInstanceAsync starts the orchestrator with the deserialized order as input and returns the new instance's ID. CreateCheckStatusResponse then builds an HttpResponseData that's an HTTP 202 (Accepted) carrying a set of management URLs (status, terminate, and so on) keyed to that instance ID. The workflow runs asynchronously; the HTTP caller gets an immediate 202 and uses the status URL to find out when the order is done. The orchestrator never starts itself, and the client never contains workflow logic; each role stays in its lane.

One pin before you copy this into a project: the Durable extension is Microsoft.Azure.Functions.Worker.Extensions.DurableTask version 1.16.5 (the 1.x line, even on .NET 10), and TaskOrchestrationContext lives in Microsoft.DurableTask while DurableTaskClient lives in Microsoft.DurableTask.Client. These are the isolated-worker types; the in-process model used different names (IDurableOrchestrationContext, a different client), and mixing the two is the most common reason a copied snippet won't compile.

Replay mechanics

The orchestrator code reads like it runs once, top to bottom. It doesn't. To understand every rule that follows, you have to start from the one mechanic that drives them all: the orchestrator function body runs many times over the life of a single workflow instance.

Durable Functions doesn't snapshot the orchestrator's current state and resume it. It uses event sourcing. Every action the orchestrator takes (an activity scheduled, an activity completed, a timer created, a result returned) is appended to an append-only log in the History table, which lives in the task hub from the previous section. That log, not the in-memory state of the function, is the source of truth for where the workflow is.

Here is what actually happens when the order orchestrator runs. The first time, it executes from the top, hits await context.CallActivityAsync<bool>(nameof(ValidateOrderActivity), order), and yields. The dispatcher commits "ValidateOrderActivity scheduled" to the History table and unloads the orchestrator from memory entirely. There is now no thread, no stack, nothing in RAM waiting; the workflow exists only as rows in storage. When the validation activity finishes, its result is written to history and the orchestrator is woken back up.

On that wake-up, the orchestrator runs again from the very first line. It reaches the same CallActivityAsync call, but this time the framework checks the History table, sees that ValidateOrderActivity already completed, and replays the result from history instead of re-running the activity. The activity does not execute a second time; the recorded true (or false) is read straight out of storage and handed back, the validated local gets the value it had on the first run, and execution fast-forwards to the first step that hasn't completed yet, CreateOrderActivity. That step is now scheduled, the orchestrator yields again, and the cycle repeats until SendConfirmationActivity returns and the orchestrator runs to completion.

This is precisely what lets a workflow survive a crash. If the host dies after creating the order but before sending the confirmation, the History table still holds "order created" with its result. When a new worker picks the instance up, it replays from the top, fast-forwards past validation and creation using the recorded results, and resumes at exactly the confirmation step. No step that already succeeded runs twice as part of recovery, because recovery is just replay against the same history.

One practical consequence shows up the first time you add a log line to an orchestrator. It fires on every replay, so a single workflow can emit the same log message several times. The context exposes context.IsReplaying so you can suppress noise from replayed execution.

[Function(nameof(OrderOrchestrator))]
public static async Task<string> RunOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context,
    ILogger logger)
{
    var order = context.GetInput<OrderRequest>()!;

    if (!context.IsReplaying)
        logger.LogInformation("Starting order for customer {CustomerId}", order.CustomerId);

    var validated = await context.CallActivityAsync<bool>(
        nameof(ValidateOrderActivity), order);
    // ... rest of the chain
}

The if (!context.IsReplaying) guard means the "Starting order" line is written once, on the genuine first pass, and skipped on every replay. Without it the line would appear once for every time the orchestrator is dispatched, roughly once per activity in the chain.

Determinism rules

Replay is also why the orchestrator is the one role with code restrictions. If the body re-executes from the top every time, then any line that produces a different value on the second run than it did on the first will make the workflow take a different path during replay than it took originally, and the state reconstructed from history no longer matches the code's decisions. So the rule is blunt: orchestrator code must be deterministic. The same inputs and the same history must always produce the same sequence of calls.

These restrictions apply only to orchestrators. Activities can do anything; that's the point of them. It's the orchestrator, and only the orchestrator, that has to behave identically on every pass.

Here is the trap, written the way it usually gets written:

// BROKEN inside an orchestrator: re-evaluates on every replay.
[Function(nameof(OrderOrchestrator))]
public static async Task<string> RunOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    var order = context.GetInput<OrderRequest>()!;

    var receivedAt = DateTime.UtcNow;       // different value every replay
    var traceId = Guid.NewGuid();           // a new GUID every replay

    var validated = await context.CallActivityAsync<bool>(
        nameof(ValidateOrderActivity), order);
    // ...
}

Both DateTime.UtcNow and Guid.NewGuid() look harmless. The problem is that the first run records one timestamp and one GUID, then every replay computes fresh ones. If receivedAt or traceId ever feeds a branch, a comparison, or an activity input, the replayed run disagrees with the recorded history and the workflow corrupts. The failure is intermittent (replay only happens after a yield, and only some values flow into decisions), which is exactly what makes it hard to catch in testing and ugly in production.

The fix is to take time and identity from the context, which returns replay-stable values:

// CORRECT: context helpers return the same value on every replay.
var receivedAt = context.CurrentUtcDateTime;   // same instant every replay
var traceId = context.NewGuid();               // same GUID every replay

context.CurrentUtcDateTime records the current UTC time on the first execution and replays that exact instant afterward. context.NewGuid() produces a replay-safe GUID the same way. (One naming gotcha: the property is CurrentUtcDateTime. Some docs prose mis-spells it CurrentDateTimeUtc, which does not exist and will not compile.)

The same reasoning rules out a few more things. Don't call new Random() in an orchestrator; if you need randomness, return it from an activity, where the result is saved to history and replayed like any other activity output. Don't read environment variables or configuration directly, since those can change between the first run and a replay hours later; pass config in as orchestrator input or fetch it from an activity. And don't do real I/O (database, file, HTTP) in the orchestrator: it would fire again on every replay, and a network call is never replay-stable anyway. Push all of it into activities.

Delays have their own replay-safe form. A Task.Delay or Thread.Sleep in an orchestrator both blocks a thread and re-evaluates on replay; the durable equivalent is context.CreateTimer, which records the wake-up time in history and releases the worker entirely until then, so a workflow can wait minutes or days without holding any resources.

People trip on this rule for a fair reason: the broken code compiles, passes a quick local test, and looks like ordinary C#. The orchestrator only betrays you under replay, and replay only happens after a yield on a worker that may not be the one that started the run. The mental shortcut that keeps you safe is to read every line of an orchestrator and ask whether it would return the same value if the method ran again right now. If the answer is no, it belongs in an activity or behind a context helper.

When to use Durable Functions vs queues

Durable Functions is not the default answer to "my functions need to talk to each other." A plain storage queue with a table for state is cheaper, simpler to provision, and entirely enough for a large class of problems. If the work is a single hand-off (one function drops a message, another picks it up, does its job, and that's the end of it) a queue is the right tool. Keep those functions stateless and idempotent, carry whatever state you need on the message itself, and you never have to think about replay rules or determinism.

The line to watch for is stateful coordination across steps. The moment you need the output of one step to drive the next, retries that don't redo work that already succeeded, results from parallel branches aggregated back together, a workflow that waits on an external event or a human approval, durable delays measured in hours or days, or a status endpoint that answers "where is order 4815 right now," a bare queue stops being enough. You can build all of that on queues and tables, but you'll be hand-rolling correlation IDs, a status table, poison-message handling, and timeout plumbing across several queues. That hand-rolled state machine is exactly the thing an orchestrator replaces, and it replaces it with code that reads like the workflow it implements.

So the honest recommendation: reach for a queue first. Don't pull in Durable Functions for a single fire-and-forget hand-off; the orchestrator's constraints and the task hub's storage footprint are real overhead that buys you nothing there. The signal to switch is the second or third piece of coordination bookkeeping you find yourself writing by hand. When you're maintaining a correlation ID and a status table and retry logic just to keep a multi-step process straight, you've already built a worse version of what Durable Functions gives you, and that's when the orchestration earns its complexity.

What's next

Chaining is the first of several orchestration patterns, and it's deliberately the simplest: a straight line of activities. The same replay engine powers fan-out/fan-in (running activities in parallel and aggregating their results), waiting on external events for human-in-the-loop approval, and durable entities for stateful objects. Each is a later part of this series, and each rests on the single fact this article was built around: the orchestrator is C# that replays.

Which coordination problem pushed you past a plain queue first: a multi-step sequence that needed to survive restarts, fan-out with result aggregation, or waiting on an external event or approval?

Deploying .NET Aspire Apps to Azure: AZD, ACA, and What Aspire Generates

Martin Oehlert — Fri, 12 Jun 2026 12:26:46 +0000

Parts 1 and 2 made one AppHost the source of truth for every connection your functions trigger on, locally. The question for Part 3 is what happens to that graph when you deploy it: which AppHost resources become real Azure infrastructure, and which trigger connections you still have to wire by hand. There are two toolchains that can do the deploy now, so the first decision is which one. This article uses azd, generates the Bicep, and reads it line by line to find the boundary where the generator stops and you take over.

From local to Azure

The AppHost is already a resource graph. Deployment reads that graph and turns it into Azure infrastructure; it is not a second pipeline you write and keep in sync with the first. That is the whole premise: the same AddAzureServiceBus("messaging") that started an emulator container in Part 2 provisions a real namespace at publish, and the same WithReference that resolved a local connection string emits an Azure role assignment and an identity-based environment variable.

Two toolchains turn that graph into Azure today:

azd (Azure Developer CLI): the mature, CI-friendly path. It detects the AppHost, generates Bicep from the resource graph, provisions, and deploys.
aspire deploy (built on the newer aspire publish / aspire do pipeline): what Microsoft now recommends as the default for new Aspire projects. The aspire.dev guidance is explicit that azd "is still supported with Aspire for existing workflows, but it is no longer the recommended default deployment path."

This article uses azd because it is the path with stable CI/CD integration, federated identity, and a documented pipeline generator, which is what most teams shipping today are on. The infrastructure both toolchains generate is the same; the commands differ. Three commands form the azd spine: azd init, azd provision, azd deploy. Knowing what each does, and where the split between them matters, is the rest of the deploy story.

The AZD workflow

azd init run from the solution directory scans the tree and detects the AppHost project. It keys off the Aspire AppHost SDK markers in the .csproj, not a folder name, and reports the detected service before writing anything:

$ azd init
? How do you want to initialize your app? Use code in the current directory

Scanning app code in current directory
  (✓) Done: Scanning app code in current directory

Detected services:

  .NET (Aspire)
  Detected in: ./AspireDemo.AppHost/AspireDemo.AppHost.csproj

azd will generate the files necessary to host your app on Azure.

Generating files to run your app on Azure:

  (✓) Done: Generating ./azure.yaml
  (✓) Done: Generating ./next-steps.md

SUCCESS: Your app is ready for the cloud!

What it writes is small. An azure.yaml at the root maps the AppHost to Azure, plus a .azure/<env>/ folder holding per-environment config and an .env file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
name: aspire-demo
services:
  app:
    language: dotnet
    project: ./AspireDemo.AppHost/AspireDemo.AppHost.csproj
    host: containerapp

host: containerapp records the target family; it does not by itself decide the infrastructure. azd reads the compute target from the AppHost, which is why the AddAzureContainerAppEnvironment("aca-env") line added in Part 3's sample matters (more on that below). With azure.yaml in place, two commands carry the deploy, and they are deliberately separate:

azd provision creates and configures the Azure resources from the generated infrastructure. It pushes no application code. Run it and you get a resource group, a Container Apps environment, a registry, the backing services, identities, and role assignments, all empty of your images. Against a real subscription, the Part 3 sample provisioned its ten resources in 6 minutes 25 seconds, the Container Apps environment alone taking 3 minutes 24 of those.
azd deploy builds your projects, pushes the images to the registry, and creates new Container Apps revisions wired to the provisioned resources. It creates no infrastructure. Same sample: 7 minutes 32 seconds to build the three Functions images plus the Redis container locally, push them, and bring the four apps up.

azd up runs both in one pass (package then provision then deploy) and is the right call when you are iterating locally and do not care about the seam. In CI/CD the seam is the point: provision changes infrastructure on a slow, reviewed cadence; deploy ships code many times a day. Splitting them lets infra changes gate behind approval while app deploys stay fast.

One honest caveat the split carries: when only infrastructure changes, azd provision updates the resources but does not refresh connection values in the already-running apps. You run azd deploy again to pick those up. The Azure docs put it plainly: when in doubt, use azd up.

What Aspire generates

This is the part worth slowing down on, because the generated infrastructure is the contract between your AppHost and Azure, and reading it tells you exactly what you own. The artifact is Bicep. (Aspire also emits an aspire-manifest.json, but it is now a deprecated compatibility format kept for azd interop, not the thing to center your mental model on. The Bicep is the truth.)

Generated from the Part 3 AppHost, the tree is one file per resource with a main.bicep that stitches them together:

main.bicep                       targetScope = 'subscription'; creates the RG, calls one module per resource
aca-env/aca-env.bicep            managed identity, ACR + AcrPull, Log Analytics, the managed environment
aca-env-acr/aca-env-acr.bicep    the container registry
host-storage/host-storage.bicep  AzureWebJobsStorage account (shared by all three functions)
app-storage/app-storage.bicep    the receipts storage account
messaging/messaging.bicep        the Service Bus namespace + orders queue
cache/cache.bicep                Redis (published as a container)
orders-http/orders-http.bicep    the HTTP-trigger function app (+ identity, + roles modules)
orders-queue/orders-queue.bicep  the queue-trigger function app (+ identity, + roles modules)
orders-sb/orders-sb.bicep        the Service Bus function app (+ identity, + three roles modules)

main.bicep targets the subscription scope, creates the resource group, and calls every module with one module block apiece. The shape is mechanical, by design: every AppHost resource has a one-to-one Bicep module, and the wiring between them is explicit parameters and outputs, not magic.

The environment module is where Aspire sets up the platform every app runs on. aca-env.bicep provisions a user-assigned managed identity, an Azure Container Registry with an AcrPull role assignment for that identity, a Log Analytics workspace, the Container Apps managed environment itself (Consumption profile), and the Aspire dashboard component:

resource aca_env 'Microsoft.App/managedEnvironments@2025-07-01' = {
  name: take('acaenv${uniqueString(resourceGroup().id)}', 24)
  location: location
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: aca_env_law.properties.customerId
        sharedKey: aca_env_law.listKeys().primarySharedKey
      }
    }
    workloadProfiles: [
      { name: 'consumption', workloadProfileType: 'Consumption' }
    ]
  }
}

Each function project becomes a Microsoft.App/containerApps resource, and the single most important detail in the tree is the last line:

resource orders_sb 'Microsoft.App/containerApps@2025-10-02-preview' = {
  name: 'orders-sb'
  // ...
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${orders_sb_identity_outputs_id}': { }
      '${aca_env_outputs_azure_container_registry_managed_identity_id}': { }
    }
  }
  kind: 'functionapp'
}

kind: 'functionapp' is not cosmetic. It is the Functions-optimized Container Apps variant, and it is what lets the platform derive KEDA autoscaler rules from your trigger attributes instead of you writing scale rules. A plain container app does not get that. Aspire emits kind: 'functionapp' on all three apps because all three are AddAzureFunctionsProject, not AddProject. The deployed apps confirm it: the three Functions apps report functionapp, the Redis container app reports nothing. One trap if you go check this yourself: ARM only returns kind from api-version 2025-07-01 onward. Query a container app with 2024-03-01 and the field is silently absent, which looks exactly like Aspire forgot to set it.

The connections from Part 2 land as identity-based environment variables, not connection strings. The Service Bus app's container carries exactly what its three WithReference calls declared:

env: [
  { name: 'messaging__fullyQualifiedNamespace', value: messaging_outputs_servicebusendpoint }
  { name: 'receipts__blobServiceUri',           value: app_storage_outputs_blobendpoint }
  { name: 'AzureWebJobsStorage__blobServiceUri', value: host_storage_outputs_blobendpoint }
  // ...table, queue, dataLake service URIs for host storage...
  { name: 'AZURE_CLIENT_ID',          value: orders_sb_identity_outputs_clientid }
  { name: 'AZURE_TOKEN_CREDENTIALS',  value: 'ManagedIdentityCredential' }
]

No secrets for Service Bus or Storage; the app authenticates as its user-assigned identity, and AZURE_TOKEN_CREDENTIALS=ManagedIdentityCredential pins the credential type so the SDK does not waste startup probing the others. Redis is the exception in this sample: because it is a containerized Redis rather than a managed Azure resource, its connection comes in as an ACA secret (connectionstrings--cache), not an identity.

For every referenced resource, Aspire generates a role assignment module. The Service Bus app gets three: AzureServiceBusDataOwner on the namespace, and Blob plus the rest of the Data Contributor set on the storage accounts it touches. Read the host-storage role module closely; it tells you the default access level:

// host-storage roles for orders-sb: three Data Contributor assignments, nothing more
resource host_storage_StorageBlobDataContributor  // ba92f5b4-...
resource host_storage_StorageTableDataContributor // 0a9a7e1f-...
resource host_storage_StorageQueueDataContributor // 974c5e8b-...

Three Data Contributor roles. No Storage Account Contributor (that is what .WithHostStorage(...) drops), and no Blob Data Owner. For most function workloads Data Contributor is enough; if your function needs to manage access policies or container ACLs, the default is too weak and you will widen it yourself.

Where the generated happy path stops: wiring Functions triggers

Everything above wired itself because this sample stays inside the supported set. That set is exactly four integrations: Azure Blob Storage, Azure Queue Storage, Azure Event Hubs, and Azure Service Bus. Hand any of those four to a Functions project with WithReference, and Aspire wires the connection, the identity, the role assignment, and the KEDA scaler. The Functions integration has been GA since 13.1, so this is dependable behavior rather than a moving target.

The boundary has sharp edges even on the happy path, and four of them show up in the Bicep you just read.

The connection name is a string you have to match by hand. On the AppHost:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithHostStorage(hostStorage)
    .WithReference(messaging, "messaging")
    .WithReference(receipts, "receipts")
    .WithReference(cache);

On the trigger:

[Function(nameof(ConfirmOrder))]
[BlobOutput("receipts/{OrderId}.json", Connection = "receipts")]
public async Task<Order?> ConfirmOrder(
    [ServiceBusTrigger("orders", Connection = "messaging")] OrderMessage message,
    CancellationToken cancellationToken)

"messaging" and "receipts" appear in both places, and they have to agree. The environment variable Aspire emits is messaging__fullyQualifiedNamespace; the trigger's Connection = "messaging" is what reads it. Misspell one side and nothing throws at deploy time. The function just never fires, because the runtime looks for a connection named after the trigger and finds none.

Matched correctly, the chain holds up live, not just on paper. A message posted to the deployed orders queue fired ConfirmOrder under the app's user-assigned identity and wrote the receipt blob, with no connection string anywhere in its environment, running on exactly the AZURE_TOKEN_CREDENTIALS=ManagedIdentityCredential setup from the generated Bicep:

2026-06-12T08:40:09.84 info: Function.ConfirmOrder.User[0]  Confirm order w24-live-001
2026-06-12T08:40:10.92 warn: Azure.Core  404 The specified container does not exist (ContainerNotFound)
2026-06-12T08:40:11.35 info: Function.ConfirmOrder[2]  Executed 'Functions.ConfirmOrder' (Succeeded, Id=71d7af99-4755-44a9-9f22-d81017f1f180, Duration=2211ms)

Two details in that log are worth knowing before you reproduce it. The 404 in the middle is not the connection failing: [BlobOutput] logs the miss and then creates the receipts container itself on first write. And the test setup needs data-plane roles you might not expect. The generated namespace and storage accounts disable key-based access (disableLocalAuth, allowSharedKeyAccess: false), so even an Owner on the subscription cannot post a test message or list the output blobs; sending the message took a temporary Azure Service Bus Data Sender assignment, and reading the receipt a Storage Blob Data Reader one. Plan both into however you smoke-test.

External HTTP ingress is off by default. Every app in the generated Bicep, including the HTTP-trigger one, has ingress: { external: false }:

ingress: {
  external: false
  targetPort: 8080
  transport: 'http'
}

The HTTP function is reachable inside the Container Apps environment, not from the internet, because the AppHost never called .WithExternalHttpEndpoints(). If you expected to curl your HTTP trigger after deploy, this is why you cannot. The live deploy spells it out in the hostnames: all four apps come back with *.internal.* FQDNs, such as orders-http.internal.nicesand-421ce770.westeurope.azurecontainerapps.io, and the only external URL in the whole deployment belongs to the Aspire dashboard.

No scale-to-zero by default. Every app has scale: { minReplicas: 1 }. The function apps do not idle down to zero; you pay for at least one replica each, always. KEDA still scales them up from triggers, but the floor stays at one. There is no rules: block in the Bicep either; the platform derives the scaler from kind: 'functionapp'. The deployed apps confirm the floor: all four run with minReplicas: 1 from the moment deploy finishes.

Step outside the four supported integrations and the wiring stops entirely:

Anything else needs WithEnvironment plus an IsPublishMode branch. WithReference exposes config to client integrations but not to triggers and bindings outside the four. For those you write the environment variable yourself, usually with a publish-mode branch that appends the __serviceUri suffix for identity-based connections, because the local and published shapes differ.
Existing or connection-string-only resources are not picked up. A resource added with AddConnectionString(...), or the IsPublishMode ? AddAzureServiceBus(...) : AddConnectionString(...) pattern the Service Bus docs suggest, is not wired into a Functions trigger. This is microsoft/aspire #6465, closed not_planned. If you were hoping to point a trigger at a pre-existing namespace, that is the gap to plan around.
HTTP-trigger access keys are not managed. Aspire does not create or rotate Functions access keys. An HTTP trigger that defaults to requiring a key has no key provisioned; you either set the auth level to anonymous or wire Key Vault secrets yourself.
A plain [BlobTrigger] does not autoscale on ACA. Only the Event Grid-based blob trigger source scales; the polling blob trigger does not. If you need a blob-driven function to scale, switch it to the Event Grid source or accept a fixed replica count.

That list is the real payoff. The four-integration happy path is genuinely good, and this sample rides it end to end. The moment your architecture needs a fifth connection type, an existing resource, a public HTTP endpoint, or scale-to-zero, you are writing the wiring, and knowing that before you deploy saves you a silent failure.

Owning the infrastructure

The instinct when you hit a gap is to open the generated Bicep and edit it. Resist that. Hand-edits to generated Bicep are overwritten the next time the generator runs, on both toolchains. There are two correct ways to own your infrastructure, and editing-then-regenerating is neither.

Customise in C# first. Most of what you would reach into Bicep for has an AppHost API, and a C# change regenerates deterministically every time. The external-ingress and min-replica gaps from the last section both close in the AppHost:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Http>("orders-http")
    .WithHostStorage(hostStorage)
    .WithExternalHttpEndpoints()                       // flips ingress external: true
    .PublishAsAzureContainerApp((infra, app) =>
        app.Template.Scale.MinReplicas = 0);           // allow scale-to-zero

ConfigureInfrastructure reaches the backing resources the same way, for firewall rules, network ACLs, or a private endpoint added with infra.Add(new PrivateEndpoint(...)). The enterprise networking story is largely C#-supported, not Bicep-only: a VNet on a new environment via WithDelegatedSubnet, existing resources via AsExisting (same subscription), a custom Log Analytics workspace via WithAzureLogAnalyticsWorkspace. The gaps that still fall back to hand-authored Bicep are narrow: reconfiguring the VNet or volumes on an existing ACA environment, cross-subscription existing references, and the AcrPull role assignment when you bring your own registry pull identity.

One change is mandatory rather than optional, and the Part 3 sample already has it:

builder.AddAzureContainerAppEnvironment("aca-env");

Aspire 9.4 removed the hybrid mode where azd silently owned the Container Apps environment for you. Without this line, aspire publish and azd have no compute target to publish into. Older tutorials that call PublishAsAzureContainerApp() with no environment declared predate that change and no longer work as written.

A management-group tag policy put the C#-first advice through a live test. The subscription this article deployed to denies any deployment whose resources are missing four tags (cost-center, owner, environment, project) with values from allowed lists, and the first azd provision failed on exactly that. The temptation at that moment is to edit tags into ten generated modules. The fix that holds is one C# class. An InfrastructureResolver participates in Azure.Provisioning's Bicep generation and visits every construct, which means it reaches resources that have no first-class customisation hook of their own, like the per-function identities:

using Azure.Provisioning;
using Azure.Provisioning.Primitives;

internal sealed class AzureTagResolver : InfrastructureResolver
{
    private static readonly Dictionary<string, string> RequiredTags = new()
    {
        ["cost-center"] = "cc-1234",
        ["owner"] = "platform-team",
        ["environment"] = "dev",
        ["project"] = "aspire-demo",
    };

    public override void ResolveProperties(ProvisionableConstruct construct, ProvisioningBuildOptions options)
    {
        base.ResolveProperties(construct, options);

        // Not every construct exposes Tags (role assignments don't), hence the probe.
        if (construct is not ProvisionableResource resource ||
            resource.GetType().GetProperty("Tags")?.GetValue(resource) is not BicepDictionary<string> tags)
        {
            return;
        }

        // Tags bound to a bicep expression reject item assignment; those resources
        // get a literal rebind in ConfigureInfrastructure instead (below).
        var bicepValue = (IBicepValue)tags;
        if (bicepValue.IsOutput || bicepValue.Expression is not null || bicepValue.Kind == BicepValueKind.Expression)
        {
            return;
        }

        foreach (var (key, value) in RequiredTags)
        {
            // ResolveProperties runs until the construct graph stabilises;
            // re-assigning an existing entry keeps it dirty and never converges.
            if (!tags.ContainsKey(key))
            {
                tags[key] = value;
            }
        }
    }
}

Registered once on the AppHost builder, it stamps every taggable resource in every module and survives every regeneration:

builder.Services.Configure<AzureProvisioningOptions>(options =>
    options.ProvisioningBuildOptions.InfrastructureResolvers.Insert(0, new AzureTagResolver()));

The two guard clauses in the resolver each cost real debugging time. The idempotency one first: ResolveProperties runs repeatedly until the construct graph stops changing, and unconditionally re-assigning a tag keeps the graph dirty, so generation never converges. The error you get for that is misleading: azd infra gen fails with apphost-manifest.json: no such file or directory, because generation never got far enough to write the manifest. The expression guard second: the Container Apps environment module routes its resources' tags through a module-level tags parameter, and assigning into a Tags dictionary bound to an expression throws Cannot assign to Tags, the dictionary is an expression or output only. The resolver skips those resources, and a ConfigureInfrastructure callback rebinds their Tags to a literal instead:

builder.AddAzureContainerAppEnvironment("aca-env")
    .ConfigureInfrastructure(infra =>
    {
        var resources = infra.GetProvisionableResources().ToList();
        var taggable = resources.OfType<ContainerAppManagedEnvironment>().Cast<ProvisionableResource>()
            .Concat(resources.OfType<OperationalInsightsWorkspace>())
            .Concat(resources.OfType<UserAssignedIdentity>());
        foreach (var resource in taggable)
        {
            resource.GetType().GetProperty("Tags")?.SetValue(resource, new BicepDictionary<string>
            {
                ["cost-center"] = "cc-1234",
                // ...the same four tags
            });
        }
    });

After those two fixes, every resource the policy evaluates carried the four tags: ten infrastructure resources and four container apps, zero edits to generated files. The detour also mapped where C# ownership ends. The resource group is declared in azd's own main.bicep, which no AppHost API reaches; tag it by hand and the next azd infra gen deletes the edit. (Role assignments carry no tags at all; ARM does not support tags on them.) If your policy evaluates resource groups too, that is a policy exemption conversation, or a reason for the lane below.

Or generate once, then own it. When you have a customization with no C# API, the supported escape hatch is to run the generator a single time and stop:

$ azd infra gen
Generating infrastructure
Analyzing Aspire Application (this might take a moment...)

That writes the infra/ tree into your repo. From there you commit it, manage it by hand, and stop regenerating. The compose-generate docs bless this workflow. The failure mode to avoid is the middle ground: editing the generated Bicep and continuing to run the generator, which wipes your edits on the next pass. Pick one lane: customise in C# and keep regenerating, or generate once and own the files.

GitHub Actions CI/CD

azd pipeline config wires the repository to Azure and drops a workflow into .github/workflows/. It creates an app registration, assigns a role, configures federated identity, and pushes the generated azure-dev.yml. OIDC is the default, which is the detail that matters: there is no client secret stored anywhere. The identity values land as repository variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID), not as the legacy AZURE_CREDENTIALS JSON secret.

The generated workflow is closer to production-ready than its reputation suggests. It does not run azd up. It already runs provision and deploy as separate steps:

permissions:
  id-token: write
  contents: read
# ...
    - name: Install azd
      uses: Azure/setup-azd@v2
    - name: Install .NET for Aspire
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 10.x
    - name: Log in with Azure (Federated Credentials)
      run: azd auth login --client-id "$AZURE_CLIENT_ID" --federated-credential-provider github --tenant-id "$AZURE_TENANT_ID"
    - name: Provision
      run: azd provision --no-prompt
    - name: Deploy
      run: azd deploy --no-prompt

What the default does not do is gate or separate the cadence. Both steps run in the same job, on every push, unreviewed. The advisable edit is to split by cadence and approval: move azd provision into its own job gated behind a GitHub Environment with required reviewers (infra changes are rare and want a human), and keep azd deploy as the frequent job on app commits. Each job needs its own id-token: write and its own azd auth login, because OIDC tokens and azd login state do not cross job boundaries. This is a hand edit, not a flag, and it ties straight back to the provision/deploy split from earlier, now enforced by the pipeline.

For configuration, azd stores per-environment values in .azure/<env>/.env and projects them into pipeline variables. Custom variables and secrets go under a pipeline: block in azure.yaml, each matching an environment key, and you rerun azd pipeline config after editing. Key Vault references via azd env set-secret (akvs://...) keep rotation out of the pipeline when stored as variables; secured Bicep parameters with no default get bundled into a single AZD_INITIAL_ENVIRONMENT_CONFIG secret on the provision step.

Closing

The boundary is the whole story. Aspire generates real, readable Bicep that wires identities, roles, and connections for the four integrations it supports, and it stops at a set of edges you can name: connection-name matching, external ingress, scale-to-zero, and everything outside those four integrations. Read the generated infrastructure once and you know which side of that line each piece of your app is on.

That closes Series 3. Part 1 made the AppHost the source of truth, Part 2 declared the Azure services as resources, and Part 3 deployed the graph and found where the generator stops.

Do you let Aspire generate your Azure infrastructure and customise it in C#, or do you generate once and own the Bicep by hand from there?

Azure Services as Aspire Resources: Service Bus, Storage, and Redis

Martin Oehlert — Fri, 05 Jun 2026 06:17:53 +0000

A [ServiceBusTrigger("orders", Connection = "messaging")] attribute doesn't hold a connection string. It holds the name "messaging", and something has to resolve that name to a real connection in every environment the function runs in. Part 1 moved one connection (host storage) out of local.settings.json and into the AppHost. The question this part answers is whether the same move holds for the connections you actually choose: a Service Bus namespace, a second storage account, a Redis cache, three services that in a traditional Functions app are three strings a developer pastes per machine and hopes match production.

The connection string problem, widened

The companion sample from Part 1 had two Functions projects sharing one host-storage emulator. That covered the connection the runtime needs for its own bookkeeping, the one injected as AzureWebJobsStorage. It didn't cover the connections your code triggers on.

Part 2 adds a third worker, OrderProcessor.ServiceBus, that consumes a Service Bus queue, dedupes against Redis, and writes a receipt blob to a storage account that isn't host storage. That one function touches three connections you name yourself:

public sealed class ConfirmOrderFunction(
    ILogger<ConfirmOrderFunction> logger,
    OrderValidator validator,
    IConnectionMultiplexer redis)
{
    [Function(nameof(ConfirmOrder))]
    [BlobOutput("receipts/{OrderId}.json", Connection = "receipts")]
    public async Task<Order?> ConfirmOrder(
        [ServiceBusTrigger("orders", Connection = "messaging")] OrderMessage message,
        CancellationToken cancellationToken)
    {
        // ...
    }
}

In a traditional setup each of those (messaging, receipts, and the Redis connection the multiplexer reads) is a string in local.settings.json, copied from the portal, kept current by hand on every machine and in every environment. Three names, three places to drift. The fix is the one from Part 1, applied three times: declare each service once in the AppHost as a resource, hand it to the Functions project by reference, and let Aspire compute the connection value per environment. What stays is the short name. "messaging" appears in the AppHost and on the trigger, and those two have to agree. The value behind the name stops being something you maintain.

The rest of this article is those three declarations and what each one resolves to.

Service Bus as an Aspire resource

The package is Aspire.Hosting.Azure.ServiceBus. Two lines in AppHost.cs declare the namespace and a queue:

var messaging = builder.AddAzureServiceBus("messaging").RunAsEmulator();
messaging.AddServiceBusQueue("orders");

AddAzureServiceBus("messaging") returns the namespace resource. Children come from AddServiceBusQueue / AddServiceBusTopic / AddServiceBusSubscription (the older AddQueue / AddTopic / AddSubscription names were obsoleted in 9.1, so a 9.x snippet from the Learn API reference won't compile against 13.x).

RunAsEmulator() is the line that earns the section. Locally it starts the Service Bus emulator as containers Aspire owns. In publish mode it's a no-op, so the same two lines provision a real namespace under azd. One declaration, two resolutions.

Two things about that emulator are worth knowing before you run it.

First, it isn't one container, it's two. The emulator needs a SQL backend, so Aspire pulls mcr.microsoft.com/azure-messaging/servicebus-emulator:2.0.0 plus mcr.microsoft.com/mssql/server:2022-latest, generates the SQL sa password, sets ACCEPT_EULA=Y on both, and injects the SQL connection into the emulator. You write one line; Aspire coordinates two containers and the secret between them. No .env file to edit.

Second, the emulator doesn't create entities at runtime. It reads a Config.json at startup and provisions exactly what's in it. Aspire generates that file from your AddServiceBusQueue("orders") declaration and mounts it, so the queue exists when the worker connects. On the live run the emulator logged Creating queue: orders then Emulator Service is Successfully Up!. If you need topics, subscriptions, or rules the emulator config supports but the fluent API doesn't reach, WithConfigurationFile and WithConfiguration are the escape hatches.

The trigger side is where Service Bus pays off the resource model, because Service Bus is one of the four integrations Aspire auto-wires into the Functions binding system. On the AppHost you hand the namespace to the worker by reference:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithHostStorage(hostStorage)
    .WithReference(messaging, "messaging");

The second argument to WithReference is the connection name. The trigger names the same string:

[ServiceBusTrigger("orders", Connection = "messaging")] OrderMessage message

That's the whole contract. Aspire computes the connection value (the emulator's local endpoint now, a real namespace under azd later) and injects it under messaging; the trigger resolves messaging and binds. The name matches because you typed it twice, not because anything derives it. Omit the second WithReference argument and it defaults to the resource name, which here is also messaging, so it would resolve either way; the explicit form is clearer about what the contract is. The worker needs Microsoft.Azure.Functions.Worker.Extensions.ServiceBus (5.24.0 against Worker 2.x) for the trigger attribute to exist.

Be honest with your team about the emulator's limits. Microsoft labels it dev/test only, production use is explicitly discouraged. It speaks AMQP over TCP, and it doesn't persist messages across a restart; entities re-provision from Config.json, but in-flight messages are gone. On Apple Silicon both images are amd64-only and run under Rosetta. That sounds like a caveat but it's the good kind: on the author's M-series machine the full message → trigger → blob path ran end to end with no special Docker flags beyond having Rosetta emulation available.

Storage beyond host storage

Part 1 used one storage resource for host bookkeeping. Application data shouldn't share it. The receipt this worker writes is your data, not the runtime's lease blobs and scaling state, so it gets its own resource:

var appStorage = builder.AddAzureStorage("app-storage").RunAsEmulator();
var receipts = appStorage.AddBlobs("receipts");

RunAsEmulator() here is Azurite, pulled as mcr.microsoft.com/azure-storage/azurite:3.35.0 and started and stopped with the AppHost. There's no npm install -g azurite, no second terminal running azurite --silent, no hand-written devstoreaccount1 string. The prerequisite step from every Functions README becomes a line in a project the team checks in.

One storage resource fans out to all three services. AddBlobs and AddQueues give you the blob and queue endpoints; AddTables gives you the table service. Note the plural: there's no singular AddTable in 13.x, and Aspire 9.4 moved these to top-level calls on the storage resource (AddBlobContainer, Add*ServiceClient on the client side), so older snippets miss the rename. Blob and Queue auto-wire into triggers the same way Service Bus does; Tables do not, and need the WithEnvironment form the last section covers.

The blob output binding is auto-wired by the same WithReference pattern:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithHostStorage(hostStorage)
    .WithReference(messaging, "messaging")
    .WithReference(receipts, "receipts")
    .WithReference(cache);

WithReference(receipts, "receipts") injects the connection the [BlobOutput(... Connection = "receipts")] attribute names. The function returns an Order, and Aspire serializes it to receipts/{OrderId}.json. The {OrderId} token in that path is worth a beat: it resolves from the Service Bus trigger's POCO, the OrderMessage that fired the function, not from any injected client. On the live run a message with OrderId w23-001 produced receipts/w23-001.json containing the serialized order. The blob binding read a value off the message that triggered it, across two different Azure services, with no glue code between them.

Ports are mapped dynamically, so never hardcode 127.0.0.1:10000; read the connection from the injected value. Azurite is in-memory by default. If you want receipts to survive a restart, WithDataVolume() or WithDataBindMount() opts into persistence.

Redis as an Aspire resource

Redis is the resource that breaks the pattern, and the break is the useful part of the section. The declaration looks like the others:

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

AddRedis (from Aspire.Hosting.Redis) runs a local Redis container with health checks; at publish it deploys containerized Redis on Container Apps. For a managed cache in production the current API is AddAzureManagedRedis (Azure Managed Redis, Entra ID auth by default). Don't reach for AddAzureRedis, PublishAsAzureRedis, or .RunAsContainer() on the Azure Redis resource; all three are [Obsolete] in 13.x.

The break is that Redis is not auto-wired into the Functions trigger system. The four integrations that feed triggers and bindings are Blob, Queue, Event Hubs, and Service Bus. Redis isn't one of them, which means WithReference(cache) on its own does not make a Redis trigger resolve. What WithReference(cache) does serve is the Aspire client integration: register IConnectionMultiplexer in the worker with one line and read the cache from code triggered by something else.

That's the path this sample uses. In Program.cs:

builder.AddRedisClient("cache");

And the function takes IConnectionMultiplexer by constructor injection and uses Redis as an idempotency gate, because Service Bus delivers at-least-once and a retry can replay the same order:

var db = redis.GetDatabase();
var firstDelivery = await db.StringSetAsync(
    $"orders:seen:{message.OrderId}", "1", when: When.NotExists);
if (!firstDelivery)
{
    logger.LogWarning("Duplicate order {OrderId}, skipping receipt", message.OrderId);
    return null;
}

One detail from the live run is worth a callout, because it's the kind of thing that costs an afternoon if you hit it raw. Aspire's 13.x Redis container ships with TLS and auth on by default: it runs redis-server --requirepass <generated> --tls-port 6379 ... with Aspire-issued certs. A naive redis-cli against it gets "Connection reset by peer" because it spoke plaintext to a TLS port. AddRedisClient("cache") handles the handshake and the generated password from the injected connection string, so the worker code stays at IConnectionMultiplexer and GetDatabase(). Hand-rolling the connection would mean configuring TLS and the secret yourself.

If you genuinely want to trigger on Redis (Pub/Sub, List, or Stream), the Microsoft.Azure.Functions.Worker.Extensions.Redis extension exists, but two things apply. The trigger attribute's first argument is an app-setting name, so you wire the connection with the WithEnvironment form from the next section rather than WithReference. And the Redis triggers run only on Elastic Premium or dedicated App Service plans, not Consumption or Flex Consumption. For the serverless default, the IConnectionMultiplexer-via-DI path above is the one that works on every plan.

How Aspire resolves dev versus production

Three declarations, three behaviors at the trigger boundary. The rule underneath them is exact, so state it exactly: Aspire auto-wires four integrations into the Functions binding system through WithReference, and those four are Blob Storage, Queue Storage, Event Hubs, and Service Bus. For one of those, WithReference(resource, "name") is the whole wiring. For anything else (Redis, Cosmos, SQL, Tables, a custom service), you set the env var yourself:

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithEnvironment("RedisConnection", cache.Resource.ConnectionStringExpression);

One line per non-auto-wired resource. Real, but bounded, and the same shape every time.

What the name buys you is single-sourcing of the connection value, not the name. WithReference(messaging, "messaging") and [ServiceBusTrigger(Connection = "messaging")] agree because you wrote "messaging" in both places. Aspire computes what that name resolves to and how that changes between local and published; it does not derive the name or check that the two spellings match. The one fully-automatic name in the whole system is AzureWebJobsStorage, injected by AddAzureFunctionsProject<T>() itself. Every other name is a contract you keep in code.

The resolution itself keys off execution context, not config files. RunAsEmulator() (Service Bus, Storage) and the local container (AddRedis) are what you get when you run the AppHost. Run azd in publish mode and RunAsEmulator() becomes a no-op, so the same declaration provisions the real Azure resource. There is no appsettings.Production.json toggling between them; the decision is whether you're running or publishing.

The connection's shape flips on publish, and this is the part that's easy to miss. Provisioned Azure resources default to identity-based connections, so a published Storage connection is a __serviceUri and a Service Bus connection is a __fullyQualifiedNamespace, not a key-bearing string. For the four auto-wired integrations Aspire emits the right suffix for you. For the escape-hatch resources you write that branch. A Tables service is the clean example: it's Storage, but not one of the auto-wired four, so locally the binding reads a connection string and on Azure it needs the identity-based service URI. You switch the env-var suffix on the execution context:

var ledger = appStorage.AddTables("ledger");

builder.AddAzureFunctionsProject<Projects.OrderProcessor_ServiceBus>("orders-sb")
    .WithEnvironment(
        builder.ExecutionContext.IsPublishMode ? "Ledger__serviceUri" : "Ledger",
        ledger.Resource.ConnectionStringExpression);

Locally that injects the Azurite table endpoint under the name Ledger; on publish the name becomes Ledger__serviceUri pointing at the provisioned account, and the Azure SDK reads managed identity off the suffix. The auto-wired four run this same switch for you; for everything else, this one line is it.

The default publish target is Azure Container Apps, which is GA; publishing as a real Function App needs Aspire.Hosting.Azure.AppService, still preview as of May 2026. Part 3 takes the publish path apart.

Three resources, one source of truth

The migration from Part 1 is additive again. The AppHost gains four declarations (a Service Bus namespace and its queue, a second storage resource, a Redis cache) and three WithReference lines on one new Functions project. The worker gains one AddRedisClient("cache") call. Those few lines start five containers when you run the AppHost: two Azurite instances (host storage and app-storage), the Service Bus emulator with its mssql/server:2022-latest backend, and Redis 8.6. You declared three services; Aspire pulled the images, generated the secrets between them, and wired every connection.

No connection strings moved into local.settings.json, because that's the file the whole exercise is removing as a source of truth. Keep FUNCTIONS_WORKER_RUNTIME in it and let Aspire own the rest; if a value is set in both, Aspire wins. One line is worth deleting on the way out: the Functions template seeds AzureWebJobsStorage to UseDevelopmentStorage=true, which starts its own Azurite and can race the one Aspire owns. Remove it and let AddAzureFunctionsProject<T>() inject host storage instead.

The honest scope: the Service Bus emulator is dev/test only and runs under Rosetta on Apple Silicon, Redis isn't auto-wired and its trigger extension is Premium-plan only, and identity-based connections on publish need one branch for the resources outside the auto-wired four. None of that is a blocker, but a teammate hits each one eventually, so put them in the README, not the postmortem.

Part 3 takes this AppHost to Azure: what azd provisions, why Container Apps is the default target, and what Aspire generates under the hood.

Of these three, which do you configure by hand today, a Service Bus connection per environment, a second storage account, or a Redis cache, and which one would you move into the AppHost first?

Getting Started with .NET Aspire for Azure Functions

Martin Oehlert — Fri, 29 May 2026 06:35:04 +0000

.NET Aspire for Azure Functions Developers
Prerequisite: Azure Functions for .NET Developers (Parts 1-9)

Part 1: Getting Started with .NET Aspire for Azure Functions (you are here)

Part 2: Azure Services as Aspire Resources: Service Bus, Storage, and Redis (coming)

Part 3: Deploying .NET Aspire Apps to Azure: AZD, ACA, and What Aspire Generates (coming)

A new developer joins, hits F5, and the Function fails on startup because their local.settings.json names the storage emulator differently from yours. The question isn't "what should they have typed" but "why is the configuration source of truth a per-machine JSON file in the first place." The .NET Aspire AppHost moves that source of truth into a project you check into source control, so the storage emulator, queues, and the Functions app itself all start from one dotnet run.

The drift surface

If you've ever helped a teammate get the ProjectOrganizationDemo sample running, you've seen the surface. Two Function Apps (OrderProcessor.Http and OrderProcessor.Queue) share one core library. Each app ships a local.settings.json.example with two values:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
  }
}

To run the sample end to end you start three processes: Azurite for the emulator, func start on the HTTP app, func start on the queue worker. Each developer rebuilds the same configuration on their machine. The two local.settings.json files are git-ignored, so the source of truth is whatever lives in two text files on every developer's laptop. Multiply by the number of joiners and the time spent on "why isn't my function starting" stops being a one-off.

The [QueueTrigger("orders")] OrderMessage message attribute in ProcessOrderFunction.cs doesn't name a Connection. It falls back to AzureWebJobsStorage, which is the connection string both apps duplicate. Every storage account, queue, and cache the Functions runtime needs has to be present, by name, in the JSON file the developer remembers to keep up to date.

The AppHost isn't here to make local.settings.json shorter. It's here to make it stop being the source of truth.

Why Aspire, and why for Functions

A plain ASP.NET API is one dotnet run. A Functions app isn't. Before any of your business logic executes it needs three things that aren't your code: the func host (the worker is launched behind it, not as a bare executable), an emulator standing in for AzureWebJobsStorage, and every trigger's connection resolved by name out of configuration. For a single web service that overhead barely registers. For the two-worker sample above it's the entire local-dev surface, and it's exactly what .NET Aspire is built to absorb. Aspire is three things at once: an orchestration model (the AppHost), a set of typed integration packages, and a local dashboard for logs and traces. The orchestration is the part that earns its place here.

The honest comparison is Aspire against the two things teams already reach for, not against nothing. The first is a shell of terminals. Today you open three: Azurite in one, func start on the HTTP app in a second, func start on the queue worker in a third, started in that order because the workers need the emulator already listening. Three log streams in three windows, three local.settings.json files feeding them, and no view of a message as it crosses from the HTTP app into the queue worker. One dotnet run on the AppHost replaces all three processes, and because both workers report to the same dashboard you get the thing the three-terminal setup structurally can't produce: a single trace that follows one POST /api/orders through the HTTP app, across the queue, and into the worker that dequeues it.

The second is docker-compose. It can model the same set: an Azurite service, two Function containers, a shared network. What it can't do is stay in .NET. Each Function project needs a Dockerfile and an image rebuild (or a mounted volume) on every change; connection strings live as literal strings in YAML or an .env file, the same drift surface in a different format; service wiring is container DNS, which has nothing to do with the Connection name the Functions runtime actually resolves; and the dashboard, traces, and health checks aren't part of the deal. The AppHost is a .NET project that references your Functions projects directly. The resource graph is C# the compiler checks, the connection a worker reads is computed from a container Aspire owns, and the same description is what later drives deployment. You trade a YAML file the build can't verify for a project it can.

The AppHost as composition root

The Aspire AppHost is a separate .NET project that boots your distributed app. It declares the resources (storage accounts, queues, Service Bus, your Functions projects) and wires them together. One dotnet run on the AppHost starts the whole set.

You don't install a workload. Aspire dropped the dotnet workload install aspire step in 9.0 and hasn't brought it back in 13.x. You install the project templates once:

dotnet new install Aspire.ProjectTemplates

The two templates you need are aspire-apphost (the orchestration project) and aspire-servicedefaults (a class library with the OpenTelemetry and health-check wiring you call from your Functions project). The AppHost does the orchestration; the service-defaults library is the one line of worker code that routes telemetry to the dashboard, and a later section wires it in.

Running dotnet new aspire-apphost -n AspireDemo.AppHost gives you a project file with no Microsoft.NET.Sdk base and the Aspire SDK pinned:

<Project Sdk="Aspire.AppHost.Sdk/13.3.5">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <IsAspireHost>true</IsAspireHost>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.Azure.Functions" Version="13.3.5" />
  </ItemGroup>
</Project>

Three notes. First, Aspire's project SDK replaces the .NET SDK base. There's no Microsoft.NET.Sdk row; the Aspire.AppHost.Sdk brings the build targets. Second, the only package reference you need is Aspire.Hosting.Azure.Functions. The AppHost runtime pieces come transitively from the SDK. Third, IsAspireHost is what marks this project for the source generator that produces the strongly-typed Projects.* references you use in the next section. (In the companion sample the committed csproj is shorter still: central package management drops the explicit Version, and a Directory.Build.props supplies the TargetFramework, so what's left is the SDK line, IsAspireHost, and one versionless PackageReference.)

The entry point file is AppHost.cs (the AppHost's entry point, not Program.cs). The generated default is two lines:

var builder = DistributedApplication.CreateBuilder(args);
builder.Build().Run();

That's the empty composition. Adding the Functions project is one more line.

The Functions app as an Aspire resource

The API is AddAzureFunctionsProject<TProject>(name). The generic parameter is the strongly-typed project reference (Aspire's source generator produces it once the project is referenced from the AppHost). The string is the name that shows up on the dashboard:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Queue>("orders-queue");

builder.Build().Run();

Don't use the generic AddProject<T> for a Functions project. The Microsoft Learn integration page is blunt about it: the Functions project "can't start properly" if you do. AddAzureFunctionsProject is the one that knows how to launch the func host instead of treating the project as a vanilla executable.

That one line is enough to run a single Functions project. The call provisions host storage (an Azurite emulator container) automatically and sets the AzureWebJobsStorage environment variable on the worker so existing [QueueTrigger("orders")] attributes resolve without changes.

For a multi-project AppHost (the ProjectOrganizationDemo shape: two Functions projects sharing one storage backend), naming the host storage explicitly is the recommended pattern:

var builder = DistributedApplication.CreateBuilder(args);

var hostStorage = builder.AddAzureStorage("host-storage").RunAsEmulator();

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Http>("orders-http")
    .WithHostStorage(hostStorage);

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Queue>("orders-queue")
    .WithHostStorage(hostStorage);

builder.Build().Run();

WithHostStorage(...) is GA in Aspire.Hosting.Azure.Functions 13.1+. It tells Aspire to skip the implicit per-project storage and share the resource you pass in. Locally that collapses to one Azurite container; in publish mode, one storage account.

Without WithHostStorage, each AddAzureFunctionsProject<T> call spins up its own implicit emulator. The Functions still run, but the dashboard shows two storage-emulator rows for what should be one logical concern. For one project that's fine; for two or more, share.

How Aspire starts the worker

Aspire never shells out to func start. The AppHost hands every resource to DCP (the Developer Control Plane), the local orchestrator bundled with the Aspire SDK, and DCP is what actually launches processes and pulls containers. For a Functions project it runs, in effect:

dotnet run --project OrderProcessor.Queue --no-build --no-launch-profile --port <dcp-assigned>

Two details that otherwise look like trivia follow directly from that command.

The first is why AddAzureFunctionsProject<T> exists at all. dotnet run on a Functions project produces a console executable, not a running Functions host. AddAzureFunctionsProject<T> is the resource type that knows to boot the isolated worker behind the func host and inject AzureWebJobsStorage; the generic AddProject<T> launches the assembly directly and the worker never starts. That's the concrete reason behind the "can't start properly" warning above.

The second is --no-build. DCP runs the project from whatever is already in its output folder; it doesn't compile first. So wherever dotnet build put the worker DLL is exactly where DCP expects it. If the csproj sets <RuntimeIdentifier> unconditionally (the "Honest scope" section walks through this), the DLL lands a directory deeper than DCP looks and the worker fails on launch. func start papered over that; dotnet run --no-build does not.

Service discovery: two cases

Host storage and user-defined connections behave differently. Host storage is auto-wired. User connections you wire yourself.

Case 1: host storage. AddAzureFunctionsProject<T>(...) injects the env var AzureWebJobsStorage into the worker process, set to the full Azurite connection string for local runs (the literal account-key form, not UseDevelopmentStorage=true). The worker reads that env var directly:

[Function(nameof(ProcessOrder))]
public Task Run(
    [QueueTrigger("orders", Connection = "AzureWebJobsStorage")] string body)
{
    // worker code unchanged from the non-Aspire setup
}

The trigger attribute didn't change. The Connection = "AzureWebJobsStorage" string still names an env var; the AppHost is just the thing setting it now. Trigger attributes that omit Connection entirely also fall back to AzureWebJobsStorage and resolve the same way.

Case 2: user-defined resources. A queue that belongs to your application (not to the host) gets a name you choose, and the trigger has to match:

var ordersStorage = builder.AddAzureStorage("orders-storage").RunAsEmulator();
var ordersQueue = ordersStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Queue>("orders-queue")
    .WithReference(ordersQueue, "OrdersConnection");

The second argument to WithReference is the literal env var the Functions runtime resolves. The trigger then names that same string:

[Function(nameof(ProcessOrder))]
public Task Run(
    [QueueTrigger("orders", Connection = "OrdersConnection")] string body)
{
    // ...
}

The contract between AppHost and worker is exactly that string. No magic mapping happens; a resource called orders-storage is not auto-injected as OrdersConnection. If the names don't match, the Functions runtime can't find the connection and the trigger fails to start.

Auto-wiring (where the second argument to WithReference is the only thing you need) covers four integrations: Azure Blob Storage, Azure Queue Storage, Azure Event Hubs, Azure Service Bus. For other resources, you wire one env var manually:

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

builder.AddAzureFunctionsProject<Projects.OrderProcessor_Http>("orders-http")
    .WithEnvironment("RedisConnection", redis.Resource.ConnectionStringExpression);

One extra line per resource. Not free, but localised.

What the worker actually receives

The claim that the AppHost is "just the thing setting the env var now" is checkable. Open the dashboard, select the orders-queue row, and look at its environment variables (the Resources page lists them per resource). For the shared-host-storage setup above, AzureWebJobsStorage is set to the full Azurite connection string, account key and all:

AzureWebJobsStorage=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8.../...;BlobEndpoint=http://127.0.0.1:<port>/devstoreaccount1;QueueEndpoint=http://127.0.0.1:<port>/devstoreaccount1;TableEndpoint=http://127.0.0.1:<port>/devstoreaccount1

Note what it is not: UseDevelopmentStorage=true. Aspire resolves the running Azurite container's mapped ports and writes the literal account-key form. That is the clearest single sign the connection string no longer lives in a file you maintain; the worker reads a value the AppHost computed at startup from a container it owns.

A second injected variable is the one that makes host logs show up:

AzureFunctionsJobHost__telemetryMode=OpenTelemetry

This is the configuration equivalent of setting "telemetryMode": "OpenTelemetry" in host.json, and Aspire sets it on the worker for you. It's why the Functions host's own logs reach the dashboard with no host.json edit.

Aspire also writes a set of hierarchical keys for its typed storage clients (Aspire__Azure__Storage__Queues__AzureWebJobsStorage__ConnectionString and siblings). The default Functions binding extensions ignore them; they matter only if the Functions project adds the matching Aspire.Azure.Storage.* client package. You can leave them unread.

The one change inside the Functions project

Everything so far lived in the AppHost; the worker code was untouched. The dashboard's logs, traces, and metrics are the exception. They need one line in each Functions project's Program.cs:

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();
builder.Build().Run();

AddServiceDefaults() comes from the aspire-servicedefaults project, a small class library you reference from each Functions project. It registers the OpenTelemetry exporter that targets the dashboard, plus health checks and HttpClient resilience. The call has to land before Build(), and the integration doc is specific that it goes on the IHostApplicationBuilder that FunctionsApplication.CreateBuilder returns, not the older HostBuilder().ConfigureFunctionsWorkerDefaults() style.

It's a no-op when you run the project standalone with func start. The OTLP exporter only activates when OTEL_EXPORTER_OTLP_ENDPOINT is set, which the AppHost does and a bare func start does not. So the same code runs both ways: under Aspire it lights up the dashboard, outside it stays quiet.

This is also where the App Insights cleanup belongs. If Program.cs still calls AddApplicationInsightsTelemetryWorkerService(), drop it (the "Honest scope" section explains why) and let AddServiceDefaults own telemetry.

The dashboard

dotnet run --project AspireDemo.AppHost boots everything and prints a line that looks like this:

Login to the dashboard at https://localhost:17281/login?t=<token>

The port is randomised by Properties/launchSettings.json (pin it there if you want a stable URL); the token is regenerated every run and persists as a browser cookie for three days. From Visual Studio or VS Code with the Aspire extension the browser opens automatically; from the CLI you ctrl-click the URL.

The dashboard has four pages worth knowing about for a Functions app:

Resources. Every resource you declared (your Functions projects, the host storage emulator, any queues or Service Bus namespaces) shows up as a row. Each row has a state (Running, Starting, Failed), endpoints, and a per-resource log tab.
Logs. Structured logs from the worker flow to the dashboard because of the AddServiceDefaults() call from the previous section, combined with the auto-injected AzureFunctionsJobHost__telemetryMode=OpenTelemetry. No host.json edits.
Traces. ASP.NET Core, HttpClient, and the Azure SDK Azure.* ActivitySources participate by default, so calls that cross those boundaries link up into one span tree.
Metrics. Microsoft.AspNetCore.*, System.Net.Http, and the .NET runtime meters are wired in by AddServiceDefaults. Per-invocation Functions metrics under a Microsoft.Azure.Functions.* meter still require explicit wiring in the worker.

Tracing is the page that pays off the multi-project setup. The sample gives CreateOrderFunction in orders-http a [QueueOutput("orders")] binding and ProcessOrderFunction in orders-queue the matching [QueueTrigger("orders")]. A single POST /api/orders then produces one connected trace that spans both apps: the inbound HTTP server span in orders-http, the Azure Storage Queue send span beneath it, and the queue-trigger span in orders-queue that fires when the message is dequeued. Two processes, one span tree, because the Azure SDK propagates W3C trace context through the queue message. That cross-process link is the thing three separate func start terminals could never show you.

The dashboard isn't a replacement for production Application Insights. It's the same OTLP data your Functions app would send to App Insights in production, except routed to a local UI you see in the first ten seconds of dotnet run.

Before and after

The migration from the original sample to the AppHost is almost entirely additive. You add two projects (the AppHost and the small service-defaults library), share the host storage, and trim the local.settings.json files. The only edit inside the existing Functions projects is the single AddServiceDefaults() line from earlier, plus a reference to the service-defaults project. The DX shift:

The "untracked config files" row is the one most teams underestimate. The file doesn't disappear; it shrinks to a single setting (FUNCTIONS_WORKER_RUNTIME). Removing it entirely is a future enhancement on the Functions team's roadmap; today's GA story has you keep it minimal but not absent.

Honest scope

A few caveats that don't fit the marketing slide.

Trigger auto-wiring is four integrations. Blob, Queue, Event Hubs, Service Bus. Anything else (Cosmos DB, Redis, SignalR, SQL, custom HTTP services) needs the WithEnvironment("Name", resource.ConnectionStringExpression) form. One extra line per resource. Real, but bounded.

local.settings.json must lose the AzureWebJobsStorage line. Leaving "AzureWebJobsStorage": "UseDevelopmentStorage=true" in the file (the template default) makes the Functions host try to spin up against Azurite directly, while Aspire is also running its own Azurite container. You end up with two emulators and a port conflict. Trim the file to:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
  }
}

Remove direct App Insights wiring from Functions. If your Program.cs calls AddApplicationInsightsTelemetryWorkerService(), drop it and rely on AddServiceDefaults (which configures the OTLP exporter the dashboard reads). Microsoft.ApplicationInsights.WorkerService 2.22.0 had a runtime conflict against Aspire that was fixed in 2.23.0; if you can't upgrade, the safer move is to remove the App Insights worker package and route everything through OpenTelemetry.

Unconditional <RuntimeIdentifier> breaks dotnet run --no-build. If your Functions csproj has <RuntimeIdentifier>linux-x64</RuntimeIdentifier> and <PublishReadyToRun>true</PublishReadyToRun> set unconditionally (a common copy-paste from a CI sample), dotnet build puts the worker DLL under bin/Debug/net10.0/linux-x64/ instead of bin/Debug/net10.0/. As the "How Aspire starts the worker" section explained, DCP loads from that path without rebuilding, so on macOS arm64 the worker crashes immediately. Scope both properties to Release:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

Publishing as a real functionapp,linux App Service is preview. The default Aspire publish target is Azure Container Apps, which is GA. If your team requires App Service plans (Consumption, Premium, Dedicated), Aspire.Hosting.Azure.AppService is the package and it's still 13.x-preview as of May 2026. Part 3 of this series covers publish targets and the trade-offs.

The local-dev story this article sells (AppHost, dashboard, Azurite + Service Bus emulators, structured logs, traces, the host-storage and user-trigger patterns) is GA in Aspire 13.1+. Nothing in the sections above is preview.

Still copying local.settings.json.example, or moved to an AppHost?

If you've migrated, what's the friction point in the workflow you didn't expect? If you haven't, what's the blocker: the one extra WithEnvironment line per non-auto-wired resource, the publish path you'd need (Container Apps versus App Service), or the trim-not-delete shape of local.settings.json?

The companion sample for this article lives at AspireDemo/ in azure-functions-samples. It reuses the existing ProjectOrganizationDemo projects, adds the AppHost and a service-defaults library above them, and trims both local.settings.json files. The migration is nearly additive: the two Functions projects are project references from the AppHost, and the only worker-code change is one AddServiceDefaults() line each, the line that routes their telemetry to the dashboard.

Part 2 of the series takes the same AppHost and adds Service Bus, additional storage, and a Redis cache as Aspire resources. Part 3 walks through the publish path with azd and Container Apps, and shows what Aspire generates under the hood.

Preparing for Migration: Decoupling Your Function Logic

Martin Oehlert — Fri, 22 May 2026 05:48:43 +0000

When does pushing logic out of the Function method actually pay off? The day the Consumption-plan batch runs past 10 minutes, the host kills the worker, and the same queue message is delivered again from the top. The trigger binding turns out to be a hosting contract, not a programming model: a queue trigger and a BackgroundService loop are two different shapes for the same job. Once the workload sits behind an injected service, swapping one shape for the other becomes a Program.cs change instead of a rewrite, and tests stop needing the Functions host.

The pattern shows up most clearly in a working sample. The MigrationDemo folder from Part 5 ships one workload (Settlement.Core) and three hosts (Functions, App Service, Container App) that all call into it. Everything below is grounded in that code.

The trigger as a thin controller

The Function method does three things and nothing else:

Receive the trigger payload. For queue, event hub, and Cosmos triggers the binding deserializes it for you. HTTP triggers do their own ReadFromJsonAsync.
Call an injected service with the deserialized command and a CancellationToken.
Return or forward the result.

Everything beyond that list (validation past the framework checks, persistence, downstream calls, business rules) belongs to a service. The rule is not "make the Function shorter", it is "make the Function disposable": the same workload has to be callable from somewhere that is not a trigger binding.

Before: the trigger doing too much

A naïve settlement function pulls a batch off the queue and processes it inline. Reading raw configuration, branching on the gateway response, sending dead-letter messages, all in the Run method:

public sealed class SettlementFunction(
    QueueClient deadLetterQueue,
    ILogger<SettlementFunction> logger)
{
    [Function(nameof(SettlementFunction))]
    public async Task Run(
        [QueueTrigger("settlement-batches", Connection = "AzureWebJobsStorage")] string body,
        CancellationToken cancellationToken)
    {
        var batch = JsonSerializer.Deserialize<SettlementBatch>(body)
            ?? throw new InvalidOperationException("Malformed batch.");

        var delayMs = int.Parse(Environment.GetEnvironmentVariable("PER_PAYMENT_DELAY_MS") ?? "50");
        var failureRate = double.Parse(Environment.GetEnvironmentVariable("FAILURE_RATE") ?? "0.02");

        var settled = 0;
        var failed = 0;

        foreach (var payment in batch.Payments)
        {
            cancellationToken.ThrowIfCancellationRequested();
            await Task.Delay(delayMs, cancellationToken);

            var hash = (uint)payment.PaymentId.GetHashCode(StringComparison.Ordinal);
            var accepted = ((hash & 0xFFFF) / 65536.0) >= failureRate;

            if (accepted)
            {
                settled++;
            }
            else
            {
                failed++;
                logger.LogWarning("Rejected {PaymentId}", payment.PaymentId);
                await deadLetterQueue.SendMessageAsync(
                    JsonSerializer.Serialize(new { payment.PaymentId, reason = "GATEWAY_DECLINED" }),
                    cancellationToken: cancellationToken);
            }
        }

        logger.LogInformation(
            "Batch {BatchId}: settled={Settled}, failed={Failed}",
            batch.BatchId, settled, failed);
    }
}

Three problems are not visible in the file, but they are visible the first time something goes wrong:

The settlement loop only runs inside the Functions worker. A Consumption-plan batch that runs past the 10-minute default timeout gets killed, and the same message comes back from scratch.
Changing the failure-rate threshold means redeploying the Function. Nothing in the loop is testable without spinning up the host.
Replacing the dead-letter queue with Service Bus is a method rewrite. The branching, the serialization, and the SDK call are tangled at the call site.

After: the contract in code

Push the loop into IPaymentSettler and the trigger collapses to its three jobs. From Settlement.FunctionApp/SettlementFunction.cs:

public sealed class SettlementFunction(
    IPaymentSettler settler,
    ILogger<SettlementFunction> logger)
{
    [Function(nameof(SettlementFunction))]
    public async Task Run(
        [QueueTrigger("settlement-batches", Connection = "AzureWebJobsStorage")] SettlementBatch batch,
        CancellationToken cancellationToken)
    {
        logger.LogInformation(
            "Function host received batch {BatchId} ({Count} payments)",
            batch.BatchId, batch.Payments.Count);

        var result = await settler.SettleAsync(batch, progress: null, cancellationToken);

        logger.LogInformation(
            "Function host completed batch {BatchId}: settled={Settled}, failed={Failed}",
            batch.BatchId, result.Settled, result.Failed);
    }
}

Five statements. The QueueTrigger binding deserializes the message into a SettlementBatch POCO before Run is called; Microsoft Learn confirms this in the queue trigger usage notes. The body of the workload sits behind IPaymentSettler.SettleAsync(SettlementBatch, IProgress<SettlementProgress>?, CancellationToken). The CancellationToken propagates through.

What does not belong, with evidence from the sample

Each rule below would show up as code in SettlementFunction.cs if it had been violated. None of them is.

Business rules. No validation, no per-payment branching, no calculation in Run. The accept/reject branch and the rejection log live in PaymentSettler.SettleAsync.
Direct Azure SDK calls. SettlementFunction.cs has no using Azure.Storage.* and never constructs a QueueClient or BlobClient. The trigger reaches the downstream payments network through IPaymentSettler, which depends on ISettlementGateway, which speaks the domain.
FunctionContext leakage. Neither Run nor IPaymentSettler declares FunctionContext. That type ships in Microsoft.Azure.Functions.Worker; if a service took it as a parameter, that service would not compile in the App Service or Container App project.
Environment-variable reads. No Environment.GetEnvironmentVariable anywhere in Settlement.Core. Configuration is IOptions<SettlementOptions> and IOptions<PaymentSettlerOptions>, bound identically across all three hosts.
Sink-specific logging. SettlementFunction takes ILogger<SettlementFunction>. No TelemetryClient, no FunctionContext.GetLogger.

Why thinness matters when the host changes

Three things in the after-snippet are bound to Microsoft.Azure.Functions.Worker: the [Function] attribute, the [QueueTrigger] attribute, and the dispatch contract that says the worker calls Run. When the host changes, those three things get rewritten. Whatever sits below the settler.SettleAsync(...) call site survives.

The MigrationDemo sample makes that claim measurable. The same IPaymentSettler.SettleAsync call appears in three host projects:

Settlement.FunctionApp/SettlementFunction.cs: queue trigger, five statements.
Settlement.AppService/Services/SettlementWorker.cs: a BackgroundService polling the same queue, with an IProgress<SettlementProgress> reporter feeding a /status endpoint.
Settlement.ContainerApp/SettlementWorker.cs: the same polling loop with no HTTP host.

Identical call signature, identical service, identical cancellation propagation. The diff between the three hosts is the activation surface and the composition root. The workload itself does not move.

Abstracting Azure SDK dependencies

The first temptation when "separating logic" is to wrap every SDK type. IBlobStore around BlobClient. IQueueClientWrapper around QueueClient. IServiceBusSenderWrapper around ServiceBusSender. Each wrapper has the same surface as the SDK, just with the namespace renamed. The indirection doubles, the testable surface does not change, and now there are two places to update when the SDK adds a method.

MigrationDemo cuts in a different place. It abstracts the workload shape, not the transport:

public interface ISettlementGateway
{
    Task<SettlementResponse> SubmitAsync(
        Payment payment,
        CancellationToken cancellationToken);
}

public interface IPaymentSettler
{
    Task<SettlementProgress> SettleAsync(
        SettlementBatch batch,
        IProgress<SettlementProgress>? progress,
        CancellationToken cancellationToken);
}

Both interfaces speak the domain. Payment and SettlementBatch are records in Settlement.Core/Models/. The downstream payments network is an ISettlementGateway; the demo wires FakeSettlementGateway (deterministic, fast, no network), and production swaps in a typed HttpClient against the real provider. The workload entrypoint is IPaymentSettler. One method each. No BlobClient, no QueueClient, no ServiceBusSender anywhere in the file.

Infrastructure clients live above `Settlement.Core`

The SDK clients still exist; they just live above the workload library. The App Service and Container App hosts both drain the same queue, and both register QueueServiceClient via Microsoft.Extensions.Azure. From Settlement.AppService/Program.cs:

builder.Services.AddAzureClients(clientBuilder =>
{
    if (!string.IsNullOrWhiteSpace(queueConnection))
    {
        clientBuilder.AddQueueServiceClient(queueConnection);
    }
    else if (!string.IsNullOrWhiteSpace(queueServiceUri))
    {
        clientBuilder.AddQueueServiceClient(new Uri(queueServiceUri));
        clientBuilder.UseCredential(new DefaultAzureCredential());
    }
    else
    {
        throw new InvalidOperationException(
            "Queue:ConnectionString or Queue:ServiceUri must be configured.");
    }
});

Two branches, one shared registration. The ConnectionString branch is for local development against Azurite; the ServiceUri branch uses DefaultAzureCredential so the production host authenticates with managed identity. The choice is config-driven, so the composition root does not change between dev and prod.

QueueServiceClient is the per-account singleton. The per-queue QueueClient is derived from it:

builder.Services.AddSingleton(sp =>
{
    var service = sp.GetRequiredService<QueueServiceClient>();
    var name = sp.GetRequiredService<IOptions<QueueOptions>>().Value.QueueName;
    return service.GetQueueClient(name);
});

SettlementWorker keeps its existing QueueClient constructor parameter; only the wiring above changed. The Container App host has the same block, with one config object difference.

The Functions host does not call `AddAzureClients`

Settlement.FunctionApp/Program.cs skips this whole section. It does not need to. The [QueueTrigger("settlement-batches", Connection = "AzureWebJobsStorage")] attribute reads the storage connection from the host's AzureWebJobsStorage setting and manages the client itself. To run the Function host on managed identity instead of a connection string, set AzureWebJobsStorage__queueServiceUri on the app's configuration and grant the function app's identity the Storage Queue Data Contributor role on the storage account. Microsoft Learn documents the suffix pattern in identity-based connections for Functions. That is a hosting change, not a code change.

Keep the asymmetry in mind when reading the three Program.cs files side by side. The App Service and Container App hosts manage the queue client themselves because their BackgroundService is the activation surface. The Function host hands that job to the binding.

Building portable service classes

A service class is portable when three rules hold. Each one rules out a specific failure I have watched bite during migration.

Rule 1: zero references to `Microsoft.Azure.Functions.*` in the project file

The portability claim has to survive grep. In MigrationDemo:

$ grep -r "Microsoft.Azure.Functions" Settlement.Core/
(no matches)

$ dotnet list package --include-transitive --project Settlement.Core/Settlement.Core.csproj | grep -i Functions
(no matches)

Settlement.Core.csproj declares three direct references, all Microsoft.Extensions.*: DI abstractions, logging abstractions, options. If anything in that list grows a transitive Microsoft.Azure.Functions.* dependency, the library is no longer host-agnostic and the migration story stops working. Make this check part of CI so it does not regress quietly.

Rule 2: configuration via `IOptions<T>` with validated binding

PaymentSettler reads its only knob through PaymentSettlerOptions:

public sealed class PaymentSettlerOptions
{
    public const string SectionName = "PaymentSettler";

    [Range(1, 100_000)]
    public int ProgressReportInterval { get; init; } = 1;
}

Every host binds the same options the same way:

builder.Services
    .AddOptions<PaymentSettlerOptions>()
    .Bind(builder.Configuration.GetSection(PaymentSettlerOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

What changes between hosts is the source of the value, not the shape:

Functions: PaymentSettler__ProgressReportInterval as an app setting, or Values:PaymentSettler:ProgressReportInterval in local.settings.json. The double underscore is the cross-platform environment-variable hierarchy delimiter that maps to : in the configuration tree.
App Service: nested JSON in appsettings.Development.json ({ "PaymentSettler": { "ProgressReportInterval": 50 } }) or the same env-var shape in the portal.
Container App: nested JSON plus the option to inject PaymentSettler__ProgressReportInterval at runtime, often via a Container Apps secret.

IConfiguration collapses all three sources into one binding call. PaymentSettler only ever sees IOptions<PaymentSettlerOptions>. Validation runs on startup, so a missing or out-of-range value fails the host before the first message is processed instead of crashing one batch in.

Rule 3: logging via `ILogger<T>`

PaymentSettler takes ILogger<PaymentSettler> in its primary constructor. Nothing else. No TelemetryClient, no FunctionContext.GetLogger, no Console.WriteLine. The sink (Application Insights, OpenTelemetry, console) is wired in each host's Program.cs; the workload never sees which one is registered.

The moment a service starts using TelemetryClient directly, it has a hard dependency on the Application Insights SDK. The Container App host might not register that. The migration story turns from "swap the host" into "audit every logging call site", which is exactly the rewrite the decoupling work was supposed to avoid.

The `BackgroundService` lifetime trap

Settlement.Core/Services/ServiceCollectionExtensions.cs registers IPaymentSettler as a singleton:

public static IServiceCollection AddSettlementCore(this IServiceCollection services)
{
    services.TryAddSingleton<IPaymentSettler, PaymentSettler>();
    return services;
}

That works because PaymentSettler is stateless past its IOptions<> snapshot. The minute a real workload grows a scoped dependency (a DbContext, a tenant-bound HttpClient), the lifetime story diverges across hosts:

The isolated Functions worker creates a scope per invocation. A scoped DbContext gets a fresh instance per message.
ASP.NET creates a scope per HTTP request, but a BackgroundService runs in the root scope. Injecting a scoped service into a BackgroundService constructor throws on startup. Microsoft Learn flags the constraint in the hosted-services guidance.
The Container App host hits the same root-scope rule because its activation surface is also a BackgroundService.

The fix is to inject IServiceScopeFactory into the BackgroundService and call CreateScope() per message, then resolve the scoped dependency from the scope. The Function host does not need that wrapping. Flag this before the first scoped dependency lands, or the App Service and Container App hosts will diverge from Functions in a way that only shows up at runtime.

Testing without the Functions runtime

A unit test that spins up the Functions host to verify a discount calculation takes four seconds to start, and goes red every time the worker SDK ships a new version. The discount calculation has nothing to do with the trigger. Push it behind IPaymentSettler and the test becomes plain xUnit construction against the service class.

PaymentSettler takes three constructor parameters, all in Microsoft.Extensions.*. The unit test resolves them by hand:

[Fact]
public async Task SettleAsync_with_all_accepting_gateway_reports_full_settlement()
{
    var batch = new SettlementBatch(
        BatchId: "test-1",
        CutoffUtc: DateTimeOffset.UtcNow,
        Payments: Enumerable.Range(0, 10)
            .Select(i => new Payment($"p-{i}", 100m, "EUR"))
            .ToList());

    var settler = new PaymentSettler(
        gateway: new AlwaysAcceptingGateway(),
        options: Options.Create(new PaymentSettlerOptions { ProgressReportInterval = 1 }),
        logger: NullLogger<PaymentSettler>.Instance);

    var result = await settler.SettleAsync(batch, progress: null, CancellationToken.None);

    Assert.Equal(10, result.Settled);
    Assert.Equal(0, result.Failed);
}

private sealed class AlwaysAcceptingGateway : ISettlementGateway
{
    public Task<SettlementResponse> SubmitAsync(Payment payment, CancellationToken ct) =>
        Task.FromResult(new SettlementResponse(payment.PaymentId, Accepted: true, ReasonCode: null));
}

No TestHostBuilder, no local.settings.json, no func start. The test runs in milliseconds. The hand-rolled AlwaysAcceptingGateway is the lever that makes the assertion deterministic: the FakeSettlementGateway shipped with the sample uses a hash-and-threshold check that is great for reproducible demos and inconvenient when the question is "what happens when this specific batch is all accepted?". Microsoft's Azure SDK unit-testing guide shows both options for Settlement.Core-style services: a hand-rolled subclass of the dependency (which is what AlwaysAcceptingGateway is here) or a mocking library like Moq or NSubstitute. Pick the mocking library when the assertion is on interactions; pick a subclass when the assertion is on behaviour.

Integration tests at the same boundary

The integration suite swaps the fake for the real implementation (a typed HttpClient against the payments network) and runs the same SettleAsync call. The trigger is still not in the picture; dotnet test walks the workload directly. For the App Service and Container App variants, the queue surface drains through QueueClient against Azurite. Azurite supports Blob and Queue in GA; the Table emulator is in preview, which is only worth flagging if the suite grows a Table dependency.

The Functions variant has no first-party in-process test host for the isolated worker. The integration story there is "run func start once per build and stimulate the queue." Microsoft documents one in-process Functions test fixture, Microsoft.DurableTask.InProcessTestHost, in the Durable Functions unit-testing guide, and it only covers Durable orchestrations. For a plain queue or HTTP trigger that does no replay, the trigger gets one smoke test per build; everything else is xUnit at the service.

The smoke test that earns its keep

One end-to-end test per build, run against func start, confirms the binding wires up. Its job is to catch "the queue name in host.json does not match what the worker reads" and similar host-configuration mistakes. It does not assert business logic; the unit suite already does that in milliseconds.

Before and after: a refactoring walkthrough

The trigger before-and-after is above. The two remaining pieces of the diff are the service IPaymentSettler resolves to and a second host that consumes the same service. Reading both alongside the Function makes the migration claim specific: there is exactly one place the workload lives, and the hosts compete to be the cheapest way to call it.

PaymentSettler.SettleAsync is what IPaymentSettler resolves to. The full method body fits on one screen, in Settlement.Core/Services/PaymentSettler.cs:

public async Task<SettlementProgress> SettleAsync(
    SettlementBatch batch,
    IProgress<SettlementProgress>? progress,
    CancellationToken cancellationToken)
{
    var settled = 0;
    var failed = 0;
    var total = batch.Payments.Count;
    var processed = 0;
    var interval = _options.ProgressReportInterval;

    logger.LogInformation(
        "Settling batch {BatchId}: total={Total}, cutoff={CutoffUtc:O}",
        batch.BatchId, total, batch.CutoffUtc);

    foreach (var payment in batch.Payments)
    {
        cancellationToken.ThrowIfCancellationRequested();

        var response = await gateway.SubmitAsync(payment, cancellationToken);

        if (response.Accepted)
        {
            settled++;
        }
        else
        {
            failed++;
            logger.LogWarning(
                "Settlement rejected for {PaymentId}: {ReasonCode}",
                payment.PaymentId, response.ReasonCode);
        }

        processed++;
        if (processed % interval == 0 || processed == total)
        {
            progress?.Report(new SettlementProgress(settled, failed, total));
        }
    }

    var final = new SettlementProgress(settled, failed, total);
    logger.LogInformation(
        "Batch {BatchId} settled: settled={Settled}, failed={Failed}",
        batch.BatchId, final.Settled, final.Failed);
    return final;
}

Constructor dependencies: ISettlementGateway, IOptions<PaymentSettlerOptions>, ILogger<PaymentSettler>. No Microsoft.Azure.Functions.*. No Azure.Storage.*. The host's identity (queue trigger vs BackgroundService vs anything else) is below the abstraction.

The App Service host is one of the hosts below it. Settlement.AppService/Services/SettlementWorker.cs extends BackgroundService, drains the same queue the Function reads, and dispatches each message through ProcessAsync:

private async Task ProcessAsync(QueueMessage message, CancellationToken cancellationToken)
{
    SettlementBatch? batch;
    try
    {
        batch = JsonSerializer.Deserialize<SettlementBatch>(message.Body.ToString());
    }
    catch (JsonException ex)
    {
        logger.LogError(ex, "Discarding malformed message {MessageId}", message.MessageId);
        await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt, cancellationToken);
        return;
    }

    if (batch is null)
    {
        await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt, cancellationToken);
        return;
    }

    var progress = new Progress<SettlementProgress>(p => status.Update(batch.BatchId, p));
    try
    {
        var result = await settler.SettleAsync(batch, progress, cancellationToken);
        status.Complete(batch.BatchId, result);
        await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt, cancellationToken);
    }
    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
    {
        throw;
    }
    catch (Exception ex)
    {
        logger.LogError(
            ex,
            "Settlement of batch {BatchId} failed; message will reappear after visibility timeout",
            batch.BatchId);
    }
}

The dispatch line that matters is await settler.SettleAsync(batch, progress, cancellationToken);. Same IPaymentSettler, same three-argument signature, same cancellation propagation as the Function. The App Service variant passes a real IProgress<SettlementProgress> (the worker keeps a live /status endpoint backed by SettlementWorkerStatus); the Function and Container App variants pass null. That is the entire workload diff between the three hosts.

What does differ between hosts is composition root and activation surface. The Function App's Program.cs is shorter because the binding owns the queue client; the App Service and Container App hosts register QueueServiceClient via AddAzureClients and derive QueueClient from it. The activation surface is [QueueTrigger] for the Function, BackgroundService.ExecuteAsync for the other two. Everything below those lines, AddSettlementCore(), the gateway registration, the options binding, the logger pipeline, is shared verbatim. The host moves; the workload does not.

Series wrap-up: where to go from here

Series 2 set out to answer one question: when does Azure Functions stop paying its freight, and what do you do about it? The six articles trace the ladder.

Running Azure Functions in Docker and Docker Pitfalls I Hit packaged the Function App into a container so the runtime moved with the code. Scaling Azure Functions made the cost ceilings visible by walking the Consumption, Premium, and Dedicated plans against real workloads. Structuring Complex Function Apps reorganised the project structure so refactoring stayed tractable as the function count grew. When Azure Functions Fight Back enumerated the four signals that justify a move: timeout walls, sprawl, coupling patterns, cost crossover. This article closes the loop by making the move mechanical. Once the trigger is a thin controller and the workload sits behind IPaymentSettler, the diff between Function App, App Service, and Container App is a Program.cs change.

Three places to go from here:

Series 3 (forthcoming) integrates .NET Aspire into the Functions workflow: AppHost orchestration, Service Bus, Storage, and Redis as Aspire resources, and azd deployment to Container Apps. The decoupled Settlement.Core library carries straight across; only the composition root learns about Aspire.
The MigrationDemo sample is the working reference: one workload, three hosts, identical behaviour. Clone it, swap the connection string for a service URI, and the production-credential path lights up against managed identity.
Microsoft Learn migration guidance covers the surface this article does not: moving from in-process to isolated worker (still relevant as the decoupling that makes any further migration tractable) and the broader App Service migration overview when the destination is not Functions at all.

The decoupling work earns its keep the first time a queue handler runs past 10 minutes and the answer is "register a BackgroundService against the same queue" instead of "rewrite the workload".

Closing question

Which Azure SDK type was hardest for you to push behind an interface: BlobClient, ServiceBusSender, or something else? Reply with the type name.

Azure Functions Beyond the Basics
Continues from Azure Functions for .NET Developers (Parts 1-9)

Part 1: Running Azure Functions in Docker: Why and How

Part 2: Docker Pitfalls I Hit (And How to Avoid Them)

Part 3: Scaling Azure Functions: Consumption vs Premium vs Dedicated

Part 4: Structuring Complex Function Apps: Project Organization

Part 5: When Azure Functions Fight Back: Signs You've Outgrown Them

Part 6: Preparing for Migration: Decoupling Your Function Logic (this article)

When Azure Functions Fight Back: Signs You've Outgrown Them

Martin Oehlert — Fri, 15 May 2026 09:41:53 +0000

Your queue handler hit the 10-minute Consumption ceiling last week. You restructured it to checkpoint, and the next month-end batch still creeps over. The question now is not how to wring one more workaround out of Functions. It is when the next workaround stops being cheaper than moving the job onto a different host. Four signals push the answer past "still cheaper": performance walls, complexity sprawl, coupling patterns the platform makes worse, and a cost crossover that arrives sooner than most teams plan for.

Performance walls you will hit

Four limits decide how far Functions can carry the workload: how long any one invocation can run, how much memory it can use, how many sockets it can hold open, and what its file system actually persists.

Execution timeout per plan

The numbers from the hosting plan timeout reference:

Cross-cutting cap: HTTP triggers that do not respond within 230 seconds are cut off by the Azure Load Balancer with HTTP 502 regardless of functionTimeout. The function keeps running but cannot return a response. Sources: HTTP trigger limits, Web request times out in App Service. For longer work, Microsoft points at the Durable Functions async HTTP pattern.

host.json: functionTimeout describes what happens at the cap: "When an execution exceeds this duration, a timeout error occurs and the language worker process restarts." The worker is killed, and in-flight invocations on it are lost. What the trigger does next is per binding:

Service Bus: PeekLock with autoComplete = true. On host crash the lock expires, and on next visibility the message reappears with DeliveryCount incremented. After MaxDeliveryCount (default 10) it lands in <queue>/$deadletterqueue (Service Bus dead-letter queues).
Storage Queue: visibility timeout per message. On host crash the storage-default 10-minute timeout takes over. After 5 failed attempts the message moves to <queue>-poison (Storage queue trigger: Peek lock).
Blob trigger: same five-attempt default, with failed blobs landing in webjobs-blobtrigger-poison (Poison blobs).
HTTP: caller already saw the 502 at 230 s. No automatic retry.
Timer: per Timer trigger: Retry behavior, "the timer trigger doesn't retry after a function fails."

A subtle one to flag: only Cosmos DB, Event Hubs, Kafka, and Timer support host-level retry policies ([FixedDelayRetry], [ExponentialBackoffRetry]). For Service Bus and Storage Queue, the binding's native retry semantics are the only mechanism (Azure Functions error handling and retries). Decorating a Service Bus trigger with [ExponentialBackoffRetry] does nothing.

The fix that lets you stay (when it can)

Most "we hit the timeout" stories are workloads that can be split into chunks with a checkpoint between them. A queue-triggered batch that processes 50,000 items in 50 ms each runs 42 minutes. The same handler that processes 500 at a time and writes a cursor blob between chunks survives any number of restarts. From the companion sample:

[Function(nameof(DrainBatchFunction))]
public async Task Run(
    [QueueTrigger("batches", Connection = "AzureWebJobsStorage")] BatchCommand command,
    CancellationToken cancellationToken)
{
    await cursors.CreateIfNotExistsAsync(cancellationToken: cancellationToken);

    var checkpoint = cursors.GetBlobClient($"batch-{command.BatchId}.cursor");
    var lastCommitted = await ReadCursorAsync(checkpoint, cancellationToken);

    await foreach (var chunk in source.ChunksAfterAsync(
                       command.BatchId, lastCommitted, _chunkSize, cancellationToken))
    {
        await ProcessAsync(chunk, cancellationToken);

        // Commit the cursor *before* the next chunk; if the worker is killed
        // immediately after this upload, the next attempt resumes here.
        await checkpoint.UploadAsync(
            BinaryData.FromString(chunk.LastItemId.ToString(CultureInfo.InvariantCulture)),
            overwrite: true,
            cancellationToken);
    }
}

The shape is what matters: chunk, process, commit cursor, repeat. Each chunk must be small enough that the worst-case batch (500 items at 50 ms = 25 s) finishes well inside the timeout. The cursor write is the moment durability shifts. On retry, ReadCursorAsync resumes at the last committed item instead of restarting at item 1.

This pattern keeps you on Functions. When the single chunk itself runs longer than the timeout (a 12-minute database query, a multi-gigabyte file copy, a 30-minute model inference), the workload has outgrown the platform. No chunk size helps.

Memory ceilings

Per-instance memory from the service limits table:

Two surprises in that list. Flex Consumption has a 512 MB SKU. Most teams reading the marketing page assume Flex starts where Premium does. And from the trigger's perspective, OOM and timeout look the same: the OS terminates the worker, the host restarts, and the per-binding retry semantics from the previous section decide whether the input is replayed or dropped. The closest official reference is the host health monitor, which can recycle the host preemptively when performance counters stay above 80% within the health-check window.

The blob trigger has a documented memory amplifier worth knowing. Microsoft's Blob trigger: Memory usage and concurrency warns that "the runtime must load the entire blob into memory more than one time during processing" if you bind to a non-streaming type, and concurrency multiplies the effect. Bind to Stream for anything past a few MB.

SNAT ports and connection exhaustion

Two distinct outbound limits, easy to confuse.

SNAT port budget per instance. From Troubleshoot intermittent outbound connection errors: "Each instance on Azure App service is initially given a preallocated number of 128 SNAT ports." Ports apply to the same destination tuple (address + port) and are reclaimed by the load balancer four minutes after the connection closes. Microsoft's recommendation is to keep usage under 100 outbound connections per unique remote endpoint per instance.

Total outbound TCP connections per instance. Consumption is capped at 600 active (1,200 total) per instance, and the runtime logs Host thresholds exceeded: Connections at the limit. Flex, Premium, and Dedicated are listed as "unbounded" (Dedicated still subject to App Service worker-size caps).

The fastest way to walk into both limits is the canonical Functions anti-pattern: new HttpClient() inside a function body. Each invocation creates a new socket pool, and sockets sit in TIME_WAIT after disposal, compounded by the four-minute SNAT reclaim. At any reasonable RPS, the 128-port budget for a destination host is exhausted, and the function sees intermittent connect failures or SocketException. The AZF0002 analyzer flags the call site at build time.

The recommended fix is IHttpClientFactory, registered once in Program.cs. From the companion sample:

var builder = FunctionsApplication.CreateBuilder(args);
builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddOptions<PaymentsOptions>()
    .Bind(builder.Configuration.GetSection(PaymentsOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

builder.Services
    .AddHttpClient<IPaymentsApi, PaymentsApi>((sp, client) =>
    {
        var options = sp.GetRequiredService<IOptions<PaymentsOptions>>().Value;
        client.BaseAddress = new Uri(options.BaseAddress);
        client.Timeout = TimeSpan.FromSeconds(options.TimeoutSeconds);
    })
    .AddStandardResilienceHandler();

The factory caches HttpMessageHandler instances (default lifetime 2 min per HttpClient lifetime management) and rotates them so DNS changes are picked up. The AddStandardResilienceHandler call layers in retry, circuit breaker, and timeout policies from Microsoft.Extensions.Http.Resilience without an extra DI dance. The function takes IPaymentsApi on its primary constructor and never calls new HttpClient() again.

One caveat from HttpClient guidelines: Recommended use: the factory shares a CookieContainer across pooled handlers. If your client depends on cookies, prefer a singleton with an explicit SocketsHttpHandler that sets PooledConnectionLifetime instead.

Database connections do not get the same fix

ADO.NET pools per process, and Functions runs one process per instance. Microsoft's SqlClient guidance is direct: "ADO.NET implements connection pooling by default. But because you can still run out of connections, you should optimize connections to the database."

The math is the trap. Each Consumption instance carries its own pool (default Max Pool Size = 100), and the platform can spin up to 200 Consumption instances (service limits). At full scale-out: 200 instances * 100 connections = 20,000 potential connections against the database. Premium is capped at 100 instances, Flex at 1,000. Most managed databases fall over well below that.

The fix lives at the database, not in Functions. Lower the pool size per instance, cap the application's max scale-out, or front the database with a connection pooler (PgBouncer, RDS Proxy equivalents on Azure Database for PostgreSQL Flexible Server).

Local file system

Three behaviours worth distinguishing.

Per-instance ephemeral temp. From Operating system functionality in App Service: %SystemDrive%\local is reserved for temporary local storage, "not persistent across app restarts." Plan-by-plan capacity ranges from 0.5 GB (Consumption) to 21-140 GB (Premium / Dedicated). Scale-out does not just reset temp. It makes the data invisible: instance A writes /tmp/cache.json, and instance B never sees it.

Persisted shares. Premium and Dedicated can mount Azure Files (SMB or NFS). Flex Consumption supports SMB and read-only Blobs but not NFS (Choose a file access strategy). SMB cold-start latency is documented at 200-500 ms on first execution.

Read-only file systems. When WEBSITE_RUN_FROM_PACKAGE is set, "the wwwroot folder is read-only and you receive an error if you write files to this directory" (Run from package: General considerations). The same page is explicit: "Don't add the WEBSITE_RUN_FROM_PACKAGE app setting to apps on the Flex Consumption plan." Flex's deployment model treats the package as read-only by design. Container Apps follows container-image semantics: image layers are read-only.

The Durable Functions provider doc gives the blunt warning: "Storing payloads to local disks is not recommended, since on-disk state isn't guaranteed to be available" (Azure Storage representation in a task hub). Anything you want to read on a different instance, or after a restart, belongs in Blob, Cosmos, or another external store.

Complexity signals that indicate a problem

Performance walls fail the workload outright. Complexity signals fail it slowly: the function count keeps climbing, the orchestration diagram keeps growing legends, and at some point you cannot describe the system without a whiteboard. None of the limits below are timeouts. They are the shape of the architecture telling you it has outgrown the deployment unit.

Durable Functions sub-orchestration sprawl

Microsoft lists three legitimate uses for CallSubOrchestratorAsync (Sub-orchestrations: When to use):

Compose reusable workflow building blocks shared across parents.
Fan out parallel instances of the same orchestrator and wait for all.
Organise a large orchestration into named, testable pieces.

If a sub-orchestration is not doing one of those three jobs, it is decoration, and the cost compounds. The same docs add a hard constraint: "Sub-orchestrations must be defined in the same app as the parent orchestration." The cross-app workaround is the HTTP 202 polling pattern, a different programming model with no parent/child semantics, no shared retry policy, and no automatic exception propagation. The reason is the task hub model: "If multiple apps use the same task hub, they compete for messages, which can result in undefined behavior, including orchestrations getting unexpectedly stuck."

The decision worth surfacing in your design review: task hub partition count is immutable after creation. Default 4, max 16. From Performance and scale: Partition count: "You can't change the partition count after you create a task hub. Set it high enough to meet expected scale-out requirements." Most teams discover this when their orchestrator throughput plateaus and they reach for the dial that does not exist.

Sprawl signals inside one app:

Parent depth of 3+ levels where the grandchild does almost no work.
Sub-orchestrators that wrap a single activity call.
Parents fanning out to sub-orchestrators that themselves fan out: one instance ID can spawn dozens of children, each consuming control queue capacity.

Orchestrator code constraints

Orchestrators replay from history every time a new event arrives. The runtime requires deterministic code: the same input must produce the same call sequence on every replay. From Orchestrator function code constraints, the following must not appear inside an orchestrator body:

DateTime.Now / DateTime.UtcNow (use context.CurrentUtcDateTime).
Guid.NewGuid() (use context.NewGuid(), which returns Type 5 UUIDs derived from instance ID).
Bindings, including the orchestration client and entity client bindings. I/O lives in activities.
Static variables and environment variables.
Direct network or HTTP calls.
Task.Run, Task.Delay, Thread.Sleep, HttpClient.SendAsync. Use context.CreateTimer for delays.

The clean rule is one sentence: orchestrators schedule, activities act. Anything that reads time, calls the network, or generates a random value belongs in an activity. The framework throws NonDeterministicOrchestrationException sometimes, but the docs are explicit: "this detection behavior won't catch all violations, and you shouldn't depend on it." Violations ship and break weeks later.

Shared external state as bottleneck

Account-level ceilings from Standard storage account scalability targets:

20,000 RPS per general-purpose v2 account in most regions, and 40,000 RPS in higher-tier regions.
Hitting any of these returns HTTP 503 Server Busy or HTTP 500 Operation Timeout.

Per-service ceilings (the ones that bite first):

Storage Queue: account 20,000 msg/s, single queue tops out at 2,000 msg/s (Queue Storage scalability, Data partitioning strategies).
Storage Table: 20,000 entities/s account-wide, 2,000 entities/s per partition (Table Storage scalability). Throttling shows as PercentThrottlingError. Date-as-partition-key is the canonical anti-pattern.
Cosmos DB hot partition: hard ceiling of 10,000 RU/s per logical partition (Partitioning and horizontal scaling), regardless of total provisioned throughput. Splitting does not help when the key is genuinely hot (Redistribute throughput). The fix is a different partition key.

Durable Functions sits on top of those numbers. Every task hub creates two Azure Tables (<hub>History, <hub>Instances), one work-item queue, one control queue per partition, and blob containers for leases and large messages (Azure Storage representation in a task hub). When several apps point at the same storage account, every one fights for the same per-partition 2,000 entities/s on the History and Instances tables. Microsoft's reliability guidance is direct: "use a separate storage account for each function app. This aspect is especially true with Durable Functions and Event Hubs triggered functions" (Best practices for reliable Azure Functions).

Service Bus session locks

The architectural smell is two or more functions in the same function app triggering on the same session-enabled queue. Sessions hold an exclusive lock per session ID (Message sessions): only one receiver at a time, per-session FIFO, default MaxDeliveryCount = 10. The Functions session host defaults are aggressive (Service Bus host.json settings): maxConcurrentSessions = 2000, maxConcurrentCalls = 16 per session. Thread starvation at high MaxConcurrentSessions is documented in the troubleshooting guide.

Two functions in the same app are not parallelising work over those sessions. They are competing for session locks. SessionLockLost shows up when the lock expires before renewal, the partition rebalances, or the AMQP link is idle for 10 minutes (Service Bus messaging exceptions: SessionLockLost). The fix is one consumer per session-enabled queue per app, period.

Function count vs feature count

Microsoft does not publish a number for "too many functions in one app", but the Function organization best practices describe the failure mode plainly:

Each function that you create has a memory footprint. While this footprint is usually small, having too many functions within a function app can lead to slower startup of your app on new instances.

Connection strings and other credentials stored in application settings gives all of the functions in the function app the same set of permissions in the associated resource. Consider minimizing the number of functions with access to specific credentials by moving functions that don't use those credentials to a separate function app.

A self-test you can run in 10 minutes:

Can you name the feature each function delivers without opening the code?
Does explaining one feature require drawing a diagram of 5+ function boundaries?
Is your function-to-feature ratio above 3:1? (50 functions for 8 features is 6:1.)
Do all functions share the same connection strings whether they use them or not?
Do load profiles inside the app diverge? (Chatty queue trigger next to memory-heavy report function.)
Does shipping one function redeploy 49 others?
Does cold start time grow with every release?
Does the same Durable task hub serve more than one feature area?

Three or more is the smell. Six or more is "this should have been split a quarter ago." The W19 split-apps approach handles the first wave of this. If splitting still leaves you fighting the platform, the article you are reading is the second wave.

Coupling patterns that fight the serverless model

Some of the worst Functions deployments do not look bad on any one screen. The handlers are clean, every function is short, the metrics are healthy. The damage is in the topology: the way the functions wire to each other multiplies cost, slows change, or quietly burns money in a loop. Four shapes show up over and over.

Sequential chains (the service with three methods)

Function A writes a message. Function B is triggered by it. Function C is triggered by B's message. Every input traverses the same three hops, with no branching and no fan-out. It is a workflow, not a serverless decomposition.

Microsoft's Pipes and Filters pattern is explicit on when not to use it: "the processing steps performed by an application aren't independent, or they have to be performed together as part of a single transaction." A three-step lockstep chain meets that condition. The same page points at Compute Resource Consolidation for the consolidation: "You can group filters that should scale together in the same process."

Cost per hop is five charges:

Source-function invocation (per-execution + GB-second).
Queue write (one transaction).
Queue read by the next function (another transaction).
Serialize + deserialize (CPU on both sides).
New consumer invocation (per-execution + GB-second again).

A three-function chain triples that. The corrected shapes are documented: collapse to one Functions invocation that calls the three operations as private methods (single trigger, single execution, no inter-function queues), or move to Durable Functions function chaining if the steps are genuinely separate but coordinated. The orchestrator keeps durable state and tracks the choreography explicitly.

Shared database schemas across Function Apps

Microsoft's Data considerations for microservices is unambiguous:

Two services shouldn't share a data store. Each service manages its own private data store, and other services can't access it directly.

Services can safely share the same physical database server. Problems occur when services share the same schema, or they read and write to the same set of database tables.

Two Function Apps on the same Azure SQL server with separate schemas is fine. Two Function Apps writing the same Orders table is the antipattern.

The cost surfaces at migration time. Additive changes (new column, new table) work. Destructive changes (rename, drop, type change, NOT NULL on a populated column) require all N apps to agree on a release order: forward-compat code shipped in advance to every app, or a coordinated cutover that removes the ability of any one app to deploy independently. Two-phase migrations (expand-and-contract) become the default. The blue/green compatibility window is the intersection of every app's deploy windows. Each schema version must be readable and writable by every prior version of every consumer that might still be running (multitenant antipatterns).

If three apps share an Orders table and one ships weekly, one biweekly, one monthly, the slowest cadence sets the floor. A hosted service that owns the schema collapses N consumers to 1, and migrations stop being a coordination problem. The trade is what you give up: per-function scaling and trigger-binding ergonomics. The Saga pattern: Context and problem acknowledges the trade explicitly.

Circular queue dependencies and poison loops

Two defaults to cite side by side, because readers conflate them:

Storage Queue maxDequeueCount = 5. After 5 failures the message goes to <originalqueue>-poison (Storage queue host.json settings).
Service Bus MaxDeliveryCount = 10. After 10 attempts the message goes to the DLQ at <queue path>/$deadletterqueue (Service Bus dead-letter queues). "There's no automatic cleanup of the DLQ. Messages remain in the DLQ until you explicitly retrieve them."

Functions handles the settlement automatically: "By default, the runtime calls Complete on the message if the function finishes successfully, or calls Abandon if the function fails" (Service Bus trigger: PeekLock). The two antipatterns that subvert this safety net:

Retry queue that re-enqueues to the input queue. Handler catches the exception, writes the message back to the input queue with a transient-failure tag, returns success. The runtime never sees a failure, dequeueCount resets each round trip, and the message lives forever. The MessageId changes because the application is publishing a new message each time, so log correlation by ID misses it.
Dead-letter handler that re-triggers the original function. A second function with a trigger on the poison/DLQ subqueue picks up failed messages and calls back into the original function's logic (or worse, writes back to the original input queue). Result: input -> processing -> poison -> handler -> input ad infinitum. Service Bus eventually surfaces QuotaExceeded (messaging exceptions). Storage Queues do not fail nearly as loudly. The loop just costs money until somebody notices the bill.

Microsoft names the failure shape directly. The Choreography pattern carries the warning: "There's a risk of cyclic dependency between saga participants because they have to consume each other's commands."

Detecting poison loops in Application Insights

The End-to-end transaction details view shows a Gantt chart of every server-side telemetry event for a correlated operation_Id across all instrumented components. For a Functions chain, each invocation shows up as a request span with the queue-dependency calls between them, all under the same operation. N+1 invocations of the same function name under the same operation_Id is the loop signature. The Application Map makes the cycle visible at the topology level: a node with a self-edge or a tight A->B->A cycle.

The detection workflow is two clicks: Failures view, drill into a sample exception, the End-to-end transaction view opens with the trace tree expanded. If you cannot tell at a glance whether a transaction is one logical request or three loops of the same one, instrument before you refactor.

Configuration drift

Splitting one Function App into N copies the configuration N times. Each app has its own connection strings, API keys, storage keys in App Settings. Rotating a secret means N updates. Missing one leaves a stale credential in production until the next deploy.

Key Vault references move the storage out of App Settings and into a vault. The syntax (Use Key Vault references as app settings) takes one of two forms:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret)
@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret)

The failure mode the same page documents: "If a reference isn't resolved properly, the reference string is used instead." Real production failure pattern: the function tries to authenticate with the literal string @Microsoft.KeyVault(...), gets a 401, and the operator stares at App Settings that look correct in the portal. The WEBSITE_KEYVAULT_REFERENCES env var holds resolution status for every reference, and the portal exposes a Key Vault Application Settings Diagnostics detector. Both are worth knowing before the first incident.

The "partially adopted" antipattern is the worst version: some apps reference @Microsoft.KeyVault(...), others have raw values because the migration was incomplete. Rotating the secret in the vault updates the references and leaves the raw-value apps stale. Configuration looks correct in the portal until the next failure surface, usually a 401 from a downstream service hours after rotation.

Azure App Configuration collapses N App Settings stores into one. "Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. Use App Configuration to store all the settings for your application and secure their accesses in one place." App Configuration handles non-secret config and holds Key Vault references for secret values. Key Vault stays the secret store. The trade is one runtime dependency, N role assignments, and refresh semantics that are opt-in (without dynamic refresh, settings are read once at startup). For two-app workloads it might not pay. For ten-app workloads it almost always does (App Configuration: high resiliency).

The cost crossover point

"Functions is too expensive at scale" and "Functions is the cheap option" are both true. They describe different points on the same curve. The crossover happens earlier than most teams plan for, and the worked example below makes it concrete.

A worked example: 10 RPS at 200 ms / 256 MB

Assumptions: 10 RPS sustained for 30 days, 200 ms execution, 256 MB memory. East US 2. Single subscription with the per-month free grants applied. All numbers verified against the Azure Retail Prices API on 2026-05-08.

Volumes:

Executions: 10 * 3,600 * 24 * 30 = 25,920,000
GB-seconds: 0.25 * 0.2 * 25,920,000 = 1,296,000

The Flex number is the trap. Flex bills a 1-second minimum per execution then rounds to 100 ms above that (Flex billing). At 200 ms / 256 MB, every invocation bills as if it ran 1 second, which is 5x the GB-seconds and pushes the bill 9x above legacy Consumption. Teams switching from Consumption to Flex "for the per-function scaling" walk into this and call the platform expensive. Verify on real workload before committing.

The crossover with EP1 is the other number worth keeping in your head. Setting Consumption_total = EP1_floor and solving for RPS at 200 ms / 256 MB:

Cost ≈ 2.592 * R - 6.60 = 145.93
R ≈ 58.8 RPS sustained

At the 200 ms / 256 MB shape, Consumption ties EP1 around 60 RPS sustained. Below that, Consumption wins on cost. Above that, EP1 starts winning and the Premium-only reasons (always-on, VNet integration, longer timeouts) compound the case. The crossover shifts with execution length: at 1 s / 256 MB it falls to about 12 RPS, and at 50 ms it pushes past 240 RPS. Pick the shape that matches your workload before you quote a number.

AKS gets one sentence: if you need Kubernetes primitives, you are no longer comparing against Functions, and the comparison belongs in a different article.

The hidden bill in App Insights

App Insights bills through Log Analytics (App Insights billing) at $2.76 per GB ingested above the 5 GB free grant per workspace. For most apps the default adaptive sampling at 5 events/second per host keeps ingestion under the grant (Sampling in Application Insights). The failure mode is operational: an engineer disables sampling to chase a bug, forgets to re-enable, and the next month's bill arrives. At 100 RPS unsampled with 10 KB telemetry events, ingestion is 86 GB/day, which is 2.6 TB/month, which is roughly $7,180/month at the PAYG rate.

The mitigation is a daily cap, set per workspace. The portal default for a workspace-based App Insights resource is 100 GB/day, but resources created via Visual Studio default to 32.3 MB/day (Daily cap). Whichever number you pick, set it before someone disables sampling.

The other hidden bill: the storage account

Every Function App requires a general-purpose storage account (Storage considerations). With one or two apps, storage is rounding error. With thirty apps after a W19-style split, it becomes a line item:

Queue triggers: every poll is a Class 2 op, roughly one per second when idle. Idle alone is 86,400 polls/day * 30 / 10,000 * $0.004 ≈ $1/month per queue. Real processing adds put + get + delete = 3 ops per message.
Durable task hubs: orchestration and history tables grow into millions of rows with replays, plus control queues, work-item queues, and instance tables. A busy task hub easily reaches $20-50/month before the orchestrator's compute cost.
Internal runtime traffic: lease blobs for the scale controller, host locks. Negligible per app, multiplied by N apps it shows up.

Microsoft's own guidance is to put each app on its own storage account, especially for Durable Functions and Event Hubs triggers. That doubles or triples your storage line item, and it is still the right call.

People-time

The cost crossover argument rarely decides the migration. People-time almost always does.

Debugging across N function apps requires correlated query plumbing in App Insights plus a mental model of which app owns which trigger.
Each function app is its own deployment unit, so coordinated releases need a release pipeline that understands ordering and rollback.
An on-call alert that fires "queue X is backing up" requires the operator to know which app owns queue X, which trigger, and which version is deployed.
Configuration drift compounds with app count, as the previous section already showed.

Cognitive load scales super-linearly with app count. It shows up as slower MTTR, not as a Functions bill line item, and that is exactly why it stays invisible until the team is exhausted.

Making the decision: stay, refactor, or migrate

Most "outgrowing Functions" complaints are organisational, not technical. Apply the W19 split-apps approach first, then revisit. The four concrete signals that say you can stay: no timeout pressure (longest job under half the plan limit), no memory pressure (peak under 60% of the instance ceiling), SNAT and connection issues fixed by IHttpClientFactory, function-to-feature ratio under 3:1. If all four hold, the platform is not the problem.

Refactor within Functions

This is W19 territory: split into multiple apps, extract a shared library, isolate triggers by scaling profile. If you are on Consumption, the next step before Premium is Flex Consumption (per-function scaling, longer timeouts, larger SKUs). The caveat from the cost section bears repeating: Flex's 1-second billing floor punishes sub-second functions. Verify on real workload before committing.

For workloads that bump the timeout but can be split, the checkpoint pattern from the Performance walls section keeps you on Functions: chunk, process, commit cursor, repeat. That keeps the trigger ergonomics, the deployment unit, and the scale controller. The cost is one cursor blob per active batch.

Extract specific functions

The middle ground. The function app stays, and one or two functions move out, usually because they hit a wall the rest of the app does not.

Long-running jobs. Hosted service in App Service, or a Container Apps job. Same business logic, no per-invocation cap. The companion sample shows the same payment-settlement workload as a BackgroundService next to its Function App original. The diff is the hosting wrapper, not the algorithm:

public sealed class SettlementWorker(
    QueueClient queueClient,
    IPaymentSettler settler,
    IOptions<QueueOptions> queueOptions,
    SettlementWorkerStatus status,
    ILogger<SettlementWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await queueClient.CreateIfNotExistsAsync(cancellationToken: stoppingToken);

        while (!stoppingToken.IsCancellationRequested)
        {
            var response = await queueClient.ReceiveMessagesAsync(
                maxMessages: _options.MaxBatchMessages,
                visibilityTimeout: TimeSpan.FromSeconds(_options.VisibilityTimeoutSeconds),
                cancellationToken: stoppingToken);

            if (response.Value.Length == 0)
            {
                await Task.Delay(_options.IdlePollingDelayMs, stoppingToken);
                continue;
            }

            foreach (var message in response.Value)
            {
                await ProcessAsync(message, stoppingToken);
            }
        }
    }
}

Same IPaymentSettler from the shared library, same queue, no per-invocation timeout. The trade is paying for an always-on worker (App Service) or accepting cold-start on first replica scale-out (Container Apps with KEDA).

Stateful workflows hitting Durable limits. Cross-app sub-orchestration is impossible, and shared task hub contention is real. Logic Apps Standard or a hosted workflow engine (Temporal, Elsa, Conductor) trades the binding ergonomics for a workflow surface that scales the way Durable does not.
CPU- or memory-bound work above EP3. Container Apps with the Dedicated workload profile, or AKS if Kubernetes is already a platform decision in your org.

Full migration

Rare. Criteria: timeout + memory + connection + cost crossover all present, all blocking, and the W19 organisational fixes have been applied without relief. The migration path is contract-first: extract HTTP triggers into thin wrappers, push business logic into testable libraries (a *.Core project consumed by both the Function App and the destination host), then move binding by binding.

The companion sample lays this out concretely. Settlement.Core is consumed unchanged by Settlement.FunctionApp (the timeout-wall starting point), Settlement.AppService (always-on, adds HTTP endpoints), and Settlement.ContainerApp (KEDA-scaled, scale-to-zero, no web host). The diffs are pure hosting concerns. The algorithm and the contract are identical. Reading the three side by side makes the migration question stop being abstract: you are pricing one wrapper against another, not rewriting the workload.

Decision matrix

The cost crossover at the bottom of the table is the one most teams reach for first. The decision rarely turns on it. It turns on people-time and on whether the abstraction is fighting your design or supporting it. When the abstraction is supporting the design, the right answer is almost always "stay and clean up the wiring."

Wrap-up

The four signals from the opening map to the four sections you just read. Timeouts, memory, sockets, and file system are the platform telling you the workload is too big. Sub-orchestration sprawl, session-lock contention, and high function-to-feature ratios are your team telling you the deployment unit is too big. Sequential chains, shared schemas, and poison loops are the topology making both worse. The cost crossover decides whether the right move is a different plan, a different host, or a different problem statement. None of the signals on its own says "migrate." Two of them at once says "look harder." Three of them blocking says "the abstraction is no longer paying its freight."

When you last looked at outgrowing Functions, did you stay and refactor, or did you extract the workload to a different host?

Azure Functions Beyond the Basics
Continues from Azure Functions for .NET Developers (Parts 1-9)

Part 1: Running Azure Functions in Docker: Why and How

Part 2: Docker Pitfalls I Hit (And How to Avoid Them)

Part 3: Scaling Azure Functions: Consumption vs Premium vs Dedicated

Part 4: Structuring Complex Function Apps: Project Organization

Part 5: When Azure Functions Fight Back: Signs You've Outgrown Them (this article)

Structuring Complex Function Apps: Project Organization

Martin Oehlert — Fri, 08 May 2026 05:52:21 +0000

Your project is past 15 functions. The next one needs different host.json concurrency than the rest, and a connection string nobody else in the app should see. Do you split into a second Function App, or change the values and live with the cross-talk? The answer turns on four constraints, none of which is cold start, even though cold start is the reason most teams give first.

When one Function App is too many

Microsoft puts the soft cap at 100 event-based triggers per app. Past that, the scale controller silently stops looking: "When your app has more than 100 event-based triggers, scale decisions are made based on only the first 100 triggers that execute."

Long before you hit 100, four constraints start to bite:

Scale. Every trigger in the app shares one scaling decision (with one Flex Consumption exception below).
Deploy cadence. One PR redeploys every function in the project.
Blast radius. Every function reads every connection string in app settings.
host.json scope. One concurrency, timeout, and retry setting for the whole app.

The official guidance punts past that: "It's hard to say how many functions should be in a single app, which depends on your particular workload." That's the honest answer, but the four constraints above are what you're actually weighing when you get to "particular workload."

Monolith vs multiple Function Apps

Each of the four constraints has a doc-citable behaviour behind it.

Scale. On Consumption and Premium, the app is the scale unit: "all functions within a function app that share resources in an instance are scaled at the same time." One spike on a Service Bus trigger pulls every HTTP endpoint along for the ride, even if those endpoints are idle.

Flex Consumption is the exception. It scales per trigger group: HTTP triggers share one set of instances, Service Bus / Event Hubs / Storage share another, Durable Functions share another. On Flex, splitting an app with one Service Bus trigger and one HTTP trigger gets you almost nothing the platform doesn't already give you. On Consumption or Premium, splitting is the only way to get that behaviour at all.

The scale-out clock matters too: "For HTTP triggers, new instances are allocated, at most, once per second. For non-HTTP triggers, new instances are allocated, at most, once every 30 seconds." A monolith cannot speed that up. Splitting can give a latency-sensitive HTTP path its own scale clock independent of a slow-scaling queue trigger sitting next to it.

Deploy cadence. "All functions in your local project are deployed together as a set of files." That's fine when one team owns one repo, ships everything together, and a bad deploy on Function A doesn't block fixing Function B. The day either of those stops being true, the monolith is in your way. Slot deployments, canary releases, and per-function rollback all assume separate apps.

Blast radius. Every function in the app reads every connection string and every Key Vault reference in app settings. Microsoft writes this as a security practice, not a sizing one: "Connection strings and other credentials stored in application settings gives all of the functions in the function app the same set of permissions in the associated resource. Consider minimizing the number of functions with access to specific credentials by moving functions that don't use those credentials to a separate function app." A single high-privilege connection string contaminates the whole app. The mitigation is a separate Function App with its own managed identity.

host.json scope. Settings in host.json apply to every function in the app within an instance. The worked example: "if you had a function app with two HTTP functions and maxConcurrentRequests set to 25, a request to either HTTP trigger would count towards the shared 25 concurrent requests." When two triggers need different concurrency budgets, you pick the looser one and accept the cross-talk, or you split the app. There is no third option.

Cold start: how much does function count actually cost?

The docs warn that "having too many functions within a function app can lead to slower startup of your app on new instances," but Microsoft publishes no numbers, so the warning sits as a vibe. I wanted to see when it starts to bite.

Three .NET 10 isolated worker apps, identical except for function count: 5, 15, and 30 minimal HTTP endpoints. No DI, no shared state, no external dependencies. For each app I spawn func start from a clean build, poll the first endpoint until it returns a 200, record wall-clock time, then kill and repeat ten times. Median across the ten runs:

Functions	Median	p10	p90	Δ vs 5-fn baseline
5	1528 ms	1481 ms	1673 ms	+0 ms
15	1552 ms	1536 ms	1728 ms	+24 ms
30	1548 ms	1542 ms	1561 ms	+20 ms

The delta is noise. Going from 5 functions to 30 cost 20 ms median on my machine, well inside the ~200 ms run-to-run variance on the same project. At this scale, function count is not where your cold-start budget goes.

That changes the case for splitting. If you're splitting a 30-function app because of cold start, the data isn't with you. The reasons that hold up are different: scaling (one trigger spike pulls everyone with it on Consumption and Premium), deployment cadence (one PR redeploys all of it), blast radius (every function in the app can read every connection string and every Key Vault reference in app settings), and host.json scope (one concurrency / timeout setting for the lot). Cold start is the argument that sounds intuitive and turns out not to land.

The absolute ~1.5 s number above includes Core Tools overhead, .NET runtime startup, and host metadata loading. Don't extrapolate it to Azure platform cold start. That's a different constant on top. The delta column is what scales with function count, and on this machine it's noise.

The methodology, the three apps, and a script you can run on your own machine to reproduce or extend the measurement (more iterations, more functions, your machine, your runtime): ColdStartBenchmark/ in the companion repo.

Sharing code without copy-paste

Two Function Apps in one solution want the same Order record, the same OrderValidator, the same IOrderStore abstraction. Project reference is the default. You reach for an internal NuGet package only when project reference stops being enough.

<!-- OrderProcessor.Core/OrderProcessor.Core.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <RootNamespace>OrderProcessor.Core</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
    <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
    <PackageReference Include="Microsoft.Extensions.Options" />
  </ItemGroup>
</Project>

Two things are missing on purpose:

No TargetFramework because the solution sets it centrally via Directory.Build.props. Whichever TFM the Function Apps use, this library matches. Microsoft's library guidance says: "DO start with including a net8.0 target or later for new libraries." If every consumer is .NET 10 isolated worker, target net10.0 and skip the netstandard2.0 ceremony.
No Microsoft.Azure.Functions.Worker.* packages. The library has zero dependency on the Functions SDK. An ASP.NET Core API or a console app could consume it without dragging in the worker host.

The second rule is the one that bites. The moment you put a [QueueTrigger] attribute or a [ServiceBusOutput] binding on a class in the shared library, you've forced Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues (or the Service Bus equivalent) onto every consumer. A non-Functions consumer can no longer use the library without dragging in the worker SDK.

Trigger and binding attributes belong with the function class, in the Function App project. Models, validators, business services, and DI extensions belong in the shared library. The Functions/ folder in each app holds the trigger code. The shared library holds everything else.

<!-- OrderProcessor.Http/OrderProcessor.Http.csproj -->
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
</ItemGroup>
<ItemGroup>
  <ProjectReference Include="..\OrderProcessor.Core\OrderProcessor.Core.csproj" />
</ItemGroup>

The HTTP app pulls in Http.AspNetCore. The Queue app pulls in Storage.Queues instead. Both reference Core for shared code.

The static-client exception

The "no statics in shared libraries" rule has a documented exception: connection-bearing clients. Microsoft's connection management guidance is explicit: "Do create a single, static client that every function invocation can use. Consider creating a single, static client in a shared helper class if different functions use the same service."

The rule is more precise than "no statics": no static application state that assumes single-instance execution. HttpClient, BlobServiceClient, CosmosClient, ServiceBusClient are intended to be shared statics. Counters, caches, and "current user" fields are not.

When project reference stops scaling

Project references work until you have more than one solution. The moment a second repo wants OrderProcessor.Core, you either git-submodule it (don't), copy-paste it (also don't), or publish it as an internal NuGet package and ship versioned releases. Azure Artifacts gives you an org-scoped feed for that, with 2 GiB free. The cost is the version-drift problem you didn't have before: now Function App A can sit on Core 1.4 while Function App B is on Core 1.7.

The default for a single solution is project reference. Switch to internal NuGet when (a) two repos consume the library, and (b) you actually need to ship them on different cadences. Anything before that is process where you needed a project reference.

Dependency injection with Keyed Services

Two Function Apps want different storage backends. The HTTP app writes through SQL because the read model needs strong consistency. The Queue app reads from Cosmos for bulk reprocessing. Both consume IOrderStore. .NET 8 added Keyed Services so you don't have to invent a factory, a sentinel type, or a Func<string, IOrderStore> per backend.

namespace OrderProcessor.Core.Stores;

public interface IOrderStore
{
    Task<Order?> GetAsync(string orderId, CancellationToken cancellationToken);
    Task SaveAsync(Order order, CancellationToken cancellationToken);
}

public sealed class SqlOrderStore(ILogger<SqlOrderStore> logger) : IOrderStore
{
    // SQL implementation
}

public sealed class CosmosOrderStore(ILogger<CosmosOrderStore> logger) : IOrderStore
{
    // Cosmos implementation
}

Both implementations register against the same interface, distinguished by a key:

public static class OrderStoreKeys
{
    public const string Sql = "sql";
    public const string Cosmos = "cosmos";
}

// OrderProcessor.Core/Services/ServiceCollectionExtensions.cs
public static IServiceCollection AddOrderServices(this IServiceCollection services)
{
    services.TryAddSingleton<OrderValidator>();

    services.TryAddKeyedSingleton<IOrderStore, SqlOrderStore>(OrderStoreKeys.Sql);
    services.TryAddKeyedSingleton<IOrderStore, CosmosOrderStore>(OrderStoreKeys.Cosmos);

    return services;
}

Three details in the snippet are load-bearing:

The keys are const string on a static class, not bare string literals at the call site. Stringly-typed keys are the failure mode: a typo in [FromKeyedServices("sqll")] throws InvalidOperationException at resolve time, not compile time. A typo in OrderStoreKeys.Sql doesn't compile. The object? parameter accepts anything that implements Equals correctly, so enums or typed records work too. const string constants are the cheapest mitigation.
TryAddKeyed* rather than AddKeyed*. Every AddKeyed* call adds a new descriptor, and GetKeyedService<T> returns the last registration, silently shadowing earlier ones. Library code that registers default keyed implementations should use TryAddKeyed* so a consumer can override without ending up with two (IOrderStore, "sql") registrations and the silent second-wins behaviour.
App-specific wiring stays in Program.cs. AddOrderServices is shared across both apps. If OrderProcessor.Http needs an HttpClient and OrderProcessor.Queue needs a ServiceBusClient, those go in their respective Program.cs files, not in the shared library.

Program.cs pulls it together:

// OrderProcessor.Http/Program.cs
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using OrderProcessor.Core.Configuration;
using OrderProcessor.Core.Services;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<OrderProcessingOptions>(
    builder.Configuration.GetSection("OrderProcessing"));

builder.Services.AddOrderServices();

builder.Build().Run();

FunctionsApplication.CreateBuilder is the recommended builder for new isolated worker projects. It loads appsettings.json automatically, where new HostBuilder() does not. The Configure<OrderProcessingOptions> line binds an options class for any per-function tunables (retry counts, batch sizes, timeouts) that you'd rather change in app settings than in code. The function injects IOptions<OrderProcessingOptions> and reads .Value. Wednesday's tip walks through IOptions<T> vs IOptionsSnapshot<T> for the cases where you need values to refresh at runtime.

Resolving the right key

The function class takes its IOrderStore directly on the primary constructor parameter:

// OrderProcessor.Http/Functions/CreateOrderFunction.cs
public sealed class CreateOrderFunction(
    ILogger<CreateOrderFunction> logger,
    OrderValidator validator,
    [FromKeyedServices(OrderStoreKeys.Sql)] IOrderStore primaryStore)
{
    [Function(nameof(CreateOrder))]
    public async Task<IActionResult> CreateOrder(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "orders")] HttpRequest req,
        [FromBody] CreateOrderRequest request,
        CancellationToken cancellationToken)
    {
        var order = new Order(request.OrderId, request.CustomerId, request.Amount, OrderStatus.Pending);

        var validation = validator.Validate(order);
        if (!validation.IsValid)
        {
            return new BadRequestObjectResult(new { error = validation.Error });
        }

        await primaryStore.SaveAsync(order, cancellationToken);

        return new CreatedResult($"/api/orders/{order.OrderId}", order);
    }
}

[FromKeyedServices] is AttributeUsage = AttributeTargets.Parameter, which is exactly where primary constructors put their parameters. No backing fields to assign, no field-name shuffle to make the key visible to the function method.

A second function in the same app can resolve a different key:

public sealed class GetOrderFunction(
    ILogger<GetOrderFunction> logger,
    [FromKeyedServices(OrderStoreKeys.Cosmos)] IOrderStore readStore)
{
    [Function(nameof(GetOrder))]
    public async Task<IActionResult> GetOrder(
        [HttpTrigger(AuthorizationLevel.Function, "get", Route = "orders/{orderId}")] HttpRequest req,
        string orderId,
        CancellationToken cancellationToken)
    {
        Order? order = await readStore.GetAsync(orderId, cancellationToken);
        return order is null ? new NotFoundResult() : new OkObjectResult(order);
    }
}

CreateOrderFunction writes through SQL. GetOrderFunction reads from Cosmos. Same Function App, same IOrderStore interface, two implementations resolved by key.

Two breaking changes worth knowing

.NET 9 changed missing-key behaviour. Before .NET 9, [FromKeyedServices("xyz")] would silently fall back to an unkeyed IService registration if no "xyz" key existed. As of .NET 9, it throws InvalidOperationException at resolve time. That's an improvement (typos no longer succeed quietly) and another reason to keep keys as compile-time constants.

.NET 10 changed KeyedService.AnyKey semantics. Two related changes: GetKeyedService(provider, type, KeyedService.AnyKey) now throws instead of resolving an arbitrary registration, and GetKeyedServices(provider, type, KeyedService.AnyKey) no longer returns services that were themselves registered against AnyKey. If you have library code using AnyKey for "give me whatever's registered", check it before the .NET 10 upgrade.

.NET 10 also added FromKeyedServicesAttribute.LookupMode so a keyed service's transitive dependencies can inherit the parent's key automatically. Useful for keyed graphs (a KeyedDataProcessor whose inner KeyedConnection should match the outer key), but skip it on the first pass. Explicit keys are easier to read.

The full working code lives in ProjectOrganizationDemo/ in the companion repo: shared Core library, two Function Apps, both keyed implementations, and a local.settings.json.example for each app.

Folder structure that holds up at 30 functions

Microsoft's official .NET isolated-worker sample groups files by trigger:

samples/FunctionApp/
├── FunctionApp.csproj
├── Program.cs
├── host.json
├── local.settings.json
├── HttpTriggerSimple/
├── HttpTriggerWithBlobInput/
├── HttpTriggerWithCancellation/
├── HttpTriggerWithDependencyInjection/
├── HttpTriggerWithMultipleOutputBindings/
└── QueueTrigger/

That's the actual tree of Azure/azure-functions-dotnet-worker/samples/FunctionApp. It's a per-trigger demo: one folder per function feature, no shared layers. It works for the sample because each folder is self-contained.

It stops working at fifteen functions. By then a Services/, a Models/, and a couple of cross-cutting concerns have accumulated, and the per-trigger folder layout has nowhere natural to put them. You either bolt Services/ on next to the trigger folders, or you switch to a layered convention.

The convention this article uses (and the one the companion sample uses) is:

OrderProcessor.Http/
├── OrderProcessor.Http.csproj
├── Program.cs
├── host.json
├── local.settings.json
├── Functions/                # trigger classes only
│   ├── CreateOrderFunction.cs
│   └── GetOrderFunction.cs
├── Models/                   # app-specific request/response types
│   └── CreateOrderRequest.cs
└── Infrastructure/           # middleware, options classes, app-specific clients

Microsoft does not document this layout for C# isolated worker. It's a community convention, not Microsoft guidance. The closest official endorsement is the Node.js v4 model docs, which explicitly recommend a src/functions/ subfolder. The .NET isolated-worker docs are silent on subfolder shape.

Three rules I follow:

Functions/ holds trigger classes only. Every file in Functions/ has a [Function] attribute. If a class has no trigger, it doesn't go here.
App-specific code is local. Reusable code goes to Core. CreateOrderRequest is a DTO only the HTTP app sees, so it lives in OrderProcessor.Http/Models/. Order, the domain record both apps share, lives in OrderProcessor.Core/Models/.
Infrastructure/ is for cross-cutting wiring, not business logic. Middleware, options classes, custom logging filters, retry policy setup. The test is "if I deleted this folder, would my domain logic break?" If yes, it belongs in Services/ or Core. If no, Infrastructure/.

host.json and local.settings.json stay in the project root. The deployment payload is explicit that they sit next to the executable, peer to your code files. There is no clever way to move them.

When the project also runs in Aspire

If the Function App is part of a .NET Aspire orchestration, OpenTelemetry, health checks, and resilience defaults move to a separate *.ServiceDefaults project. The Aspire docs are explicit: "If your project is part of an Aspire orchestration, it uses OpenTelemetry for monitoring instead. Don't enable direct Application Insights integration within Aspire projects." When you go Aspire, the Infrastructure/ folder mostly empties into ServiceDefaults, and Program.cs becomes one extra builder.AddServiceDefaults() call.

When to split, when to keep together

The four constraints from the opening turn into a checklist. Split when one or more of these flips from "no" to "yes":

Independent scale needs. Two triggers in the same app share scaling on Consumption and Premium. If a queue trigger scales to 50 instances during a backlog burn-down, the HTTP endpoint comes along, even when nobody is calling it.
Independent deploy cadence. A team that wants to canary the orders API without redeploying the inventory worker. A risky change to one function that shouldn't block hotfixing another. Per-slot deployments per app.
Different host.json. Two HTTP endpoints, one needs maxConcurrentRequests: 25, the other 200. There is no way to set this per function inside one app.
Credential boundary. A function reads a high-privilege Cosmos connection string. Every other function in the app inherits the same read access. The mitigation is a separate app with its own managed identity.
Test code mixed with prod. The scalability guide says it directly: "If you're using a function app in production, don't add test-related functions and resources to it." Memory is shared inside the app. So is everything else.

Keep together when:

Shared state. A function that pre-warms a cache another function reads. They depend on co-location to be cheap.
Single team, single repo, related triggers. Small surface, no cross-team friction, the functions evolve together. The overhead of a second app pays for nothing.
Low traffic. The app handles three requests a minute. Splitting trades one infrastructure unit for two with no operational gain.

Two reasons that sound good and are on neither list:

Cold start. The benchmark above shows function count is not where your cold-start budget goes at 5-30 functions per app. If you're splitting for cold start, the data isn't with you.
"It feels too big." Aesthetic discomfort with a 20-function project is not a constraint. Pick a doc-citable reason from the list above, or accept the discomfort.

Wrap-up

The split-or-keep decision belongs to your scaling, deploy, credential, and host.json constraints. The size of the project is a symptom, not a reason. A 30-function monolith with one team, one deploy cadence, and one credential set is fine. Two functions with conflicting host.json settings are not.

Keyed Services on a primary constructor is the cleanest way to handle "two implementations of one interface" once you're inside a single app. A pure shared library (zero Microsoft.Azure.Functions.Worker.* references) is what keeps those abstractions reusable across multiple Function Apps without dragging the worker SDK into every consumer.

When you last split a Function App, what was the line that forced it: a host.json setting that needed two different values, or a credential that shouldn't be visible to every function in the project?

Scaling Azure Functions: Consumption vs Premium vs Dedicated

Martin Oehlert — Fri, 01 May 2026 03:45:15 +0000

Azure Functions Beyond the Basics
Continues from Azure Functions for .NET Developers (Parts 1-9)

Part 1: Running Azure Functions in Docker: Why and How

Part 2: Docker Pitfalls I Hit (And How to Avoid Them)

Part 3: Scaling Azure Functions: Consumption vs Premium vs Dedicated (you are here)

Your Consumption plan function works fine in dev. Then production traffic arrives, the app scales to zero during a quiet period, and the next request takes 6.8 seconds. The question that follows is always the same: do you switch to Premium at $146/month, or is there something between free-with-cold-starts and always-warm-but-always-billing? Azure Functions has five hosting options now (Consumption, Flex Consumption, Premium, Dedicated, and Container Apps), each with a different billing model and a different answer to that question. This article covers the four App Service-based plans; Container Apps is a different deployment model aimed at containerized microservices. All code samples are in the companion repo.

Consumption: true serverless, true cold starts

Microsoft now labels the Consumption plan as "legacy" in its hosting docs and is directing new serverless workloads to Flex Consumption. But Consumption is still where most Functions apps start, and where many should stay. You deploy your code, the platform handles the rest. No servers to manage, no capacity to plan. You pay only when your functions execute.

How the scale controller works

The scale controller monitors event rates for each trigger type and decides how many instances to run. Since runtime v4.19.0, it uses target-based scaling by default. The formula is one division:

desired instances = event source length / target executions per instance

What "event source length" means depends on the trigger. For Storage Queues, it's queue length. For Service Bus, active message count. For Event Hubs, unprocessed events per partition. For Cosmos DB, pending changes in the change feed. The controller reads these signals and adjusts instance count accordingly.

The controller adds up to four instances at a time. HTTP triggers get new instances at most once per second. Non-HTTP triggers scale at most once every 30 seconds. This is fast enough for gradual traffic ramps but won't help with sudden spikes from zero.

Instance limits and billing

Each Consumption instance gets 1.5 GB of memory and one CPU core. The maximum instance count is 200 on Windows and 100 on Linux (with a 500-instance-per-subscription-per-hour rate limit on Linux).

Billing has two components:

Executions: $0.20 per million, with 1,000,000 free per month
Execution time: $0.000016 per GB-second, with 400,000 GB-seconds free per month

Memory is rounded up to the nearest 128 MB bucket. Execution time rounds to the nearest millisecond, with a minimum billable unit of 128 MB x 100 ms. For a function that runs a few thousand times a day at under a second each, you'll stay well inside the free grant.

Cold start reality on .NET

After roughly 20 minutes of inactivity, the Consumption plan scales to zero. The next request waits for the platform to provision a fresh instance and start your application from scratch.

On .NET isolated worker, that cold start typically lands between 2 and 7 seconds. Heavy DI registrations push it past 10. The in-process model was faster, but Microsoft is retiring it in November 2026.

For timer triggers, queue processors, and other background work, a few seconds of cold start is invisible. For HTTP endpoints that a user is waiting on, it's a problem.

What Consumption can't do

The hard constraints that push teams to other plans:

No VNet integration. If your function needs to reach resources inside a virtual network, Consumption is off the table.
10-minute execution timeout. The default is 5 minutes, configurable to 10. Long-running orchestrations or batch jobs need a different plan.
No per-function scaling. All functions in the app scale together. A chatty timer trigger can cause the platform to allocate instances that your HTTP trigger didn't need.
600 active outbound connections per instance. Hit this with parallel HTTP calls to external APIs and requests start failing.

Linux Consumption is retiring September 30, 2028. Microsoft is directing all new Linux serverless workloads to Flex Consumption. If you're starting a new project on Linux, skip Consumption entirely.

Flex Consumption: the middle ground

Flex Consumption is the plan Microsoft now recommends for new serverless workloads. It addresses the two biggest Consumption limitations: no VNet support and no way to reduce cold starts without jumping to a $146/month Premium plan.

The plan scales to zero like Consumption, but adds always-ready instances that you can configure to stay warm. It supports VNet integration out of the box. And it scales to 1,000 instances instead of Consumption's 200.

Always-ready instances vs on-demand

By default, Flex Consumption behaves like regular Consumption: zero instances when idle, on-demand instances when events arrive. The difference is you can configure always-ready instances that stay running regardless of traffic.

Always-ready instances are assigned to scale groups:

http: all HTTP and SignalR triggers
durable: orchestration, activity, and entity triggers
blob: Event Grid-based blob triggers
function:<FUNCTION_NAME>: a specific function

Setting always-ready to 2 for the http group keeps two instances permanently running for HTTP functions. Those handle traffic first. If demand exceeds their capacity, the platform adds on-demand instances on top.

az functionapp scale config set \
  --resource-group my-rg \
  --name my-func-app \
  --always-ready http=2

On-demand instances scale to zero when idle. Always-ready instances are billed continuously whether they're executing functions or not. If you enable zone redundancy, the minimum is 2 always-ready instances per group.

Billing: per-second, not per-execution

Flex Consumption bills differently from Consumption. Instead of per-execution pricing with sampled memory, you choose a fixed instance size upfront and pay per GB-second of active execution time:

On-demand rates are $0.000026 per GB-second and $0.40 per million executions. The monthly free grant is smaller than Consumption: 250,000 executions and 100,000 GB-seconds (compared to Consumption's 1,000,000 and 400,000).

Always-ready instances have a separate billing structure with no free grant. The baseline (idle) rate is $0.000004 per GB-second, roughly 6.5x cheaper than the on-demand execution rate. When always-ready instances are actively executing, the execution time rate is $0.000016 per GB-second (the same as Consumption's rate, and cheaper than on-demand).

The minimum billable execution is 1,000 ms (1 second). After that, billing rounds to the nearest 100 ms. This is less granular than Consumption's per-millisecond rounding, so very fast functions (under 100 ms) cost relatively more on Flex.

Each instance also gets an extra 272 MB platform buffer that isn't billed. This is memory the Functions host and worker process use, not your function code.

Scale behavior

Flex Consumption scales per function by trigger type. HTTP and SignalR triggers scale together. Durable Functions triggers scale together. Blob triggers (Event Grid source) scale together. Everything else scales independently per function. This fixes a real problem from Consumption, where a noisy timer trigger could cause unnecessary instance allocation for your HTTP functions.

Maximum instances: 1,000 (default limit is 100, configurable via CLI). All Flex Consumption apps in a subscription and region share a regional quota of 250 cores by default. The formula: instances x cores per instance (0.25 for 512 MB, 1 for 2,048 MB, 2 for 4,096 MB). One app running 1,000 instances at 512 MB consumes the entire quota (1,000 x 0.25 = 250 cores). You can request an increase through Azure support, but plan for this limit when running multiple Flex apps in the same region.

The constraints to know about

Flex Consumption comes with real limitations:

One app per plan. Consumption and Premium let you put up to 100 function apps on one plan. Flex is one-to-one.
No deployment slots. Rolling updates are in public preview as an alternative (zero-downtime deployments without slot swaps), but if your deployment strategy depends on slot swaps, this is a blocker today.
Linux only. No Windows support.
Isolated worker only. The C# in-process model is not supported.
App init timeout: 30 seconds. If your startup code takes longer, the instance fails to initialize. This is not configurable.
Blob trigger uses Event Grid only. The polling-based blob trigger is not available.

Flex Consumption also supports Azure Files storage mounts, letting you mount SMB shares as local directories. This is useful for large binaries, ML models, or shared reference data that you don't want to package in your deployment.

The Linux-only constraint is less of an issue than it sounds. Linux is where .NET Functions performance is best, and the in-process model (the main reason teams stayed on Windows) is being retired anyway.

VNet integration works the same way as Premium: subnet delegation to Microsoft.App/environments, support for private endpoints on storage accounts, Key Vault references over VNet, and native virtual network triggers for non-HTTP event sources.

Premium: warm instances, guaranteed

Premium (Elastic Premium) is the plan teams reach for when cold starts become unacceptable. It keeps at least one instance running at all times, so your functions never start from zero. That guarantee comes with a price floor: even with zero traffic, you're billed for that minimum instance.

What you get for $146/month

Billing is per-second based on vCPU-seconds and GB-seconds allocated across instances. No per-execution charge. The EP1 cost breaks down to ~$116.80/vCPU/month + ~$8.32/GB/month at pay-as-you-go rates in US regions. Savings plans (1-year or 3-year commitments) offer roughly 17% off.

There is no free grant on Premium. From the moment your plan exists, the meter is running.

Pre-warmed instances and elastic scale

Premium uses two layers to eliminate cold starts:

Always-ready instances run continuously, regardless of load. You configure how many per app, up to 20. These are billed 24/7, executing or not. If you have multiple function apps on the same Premium plan, the plan's minimum instance count equals the highest always-ready count among all apps.

Prewarmed buffer instances sit behind the always-ready pool. The default is 1. When all active instances are handling traffic, the prewarmed instance swaps to active and the platform immediately provisions a new buffer instance to take its place. This means scale-out events get a warm instance instead of a cold one.

You can define a warmup trigger that runs during the prewarming window. This is where you force-initialize lazy dependencies, open database connections, and prime HTTP connection pools before the instance receives real traffic:

public class Warmup
{
    private readonly HttpClient _httpClient;
    private readonly Lazy<ExpensiveAnalyticsClient> _analytics;

    public Warmup(HttpClient httpClient, Lazy<ExpensiveAnalyticsClient> analytics)
    {
        _httpClient = httpClient;
        _analytics = analytics;
    }

    [Function("Warmup")]
    public void Run([WarmupTrigger] object warmupContext)
    {
        _ = _analytics.Value;
        _ = _httpClient.GetAsync("/health", HttpCompletionOption.ResponseHeadersRead);
    }
}

The warmup trigger only fires during scale-out, not on restarts or deployments. It's available on Premium and Flex Consumption, not on the Consumption plan.

Elastic scale can burst up to 100 instances on Windows and 20-100 on Linux depending on region. Scaling beyond the minimum is best-effort: the platform allocates instances as fast as it can, but rapid spikes can outpace the prewarmed buffer. When that happens, you get cold starts even on Premium.

VNet and other features

VNet integration is supported but not automatic. You configure it at creation time or after, using regional VNet integration with a dedicated subnet (at least 100 available IPs). Private endpoints for inbound traffic are fully supported: you can create a private IP in your VNet and restrict all public access.

Non-HTTP triggers from VNet-secured resources (Service Bus with private endpoints, for example) require enabling Runtime Scale Monitoring. Without it, the scale controller can't read the event source metrics to decide when to scale.

Other features that set Premium apart:

Execution timeout: 30 minutes default, configurable to unbounded. Consumption caps at 10 minutes.
Deployment slots: 3 (including production). Consumption gets 2, Flex gets 0.
Apps per plan: up to 100 function apps on a single Premium plan, sharing the VM pool.
Custom Linux container images are supported.

When Premium is the wrong call

The most common mistake is jumping to Premium from Consumption solely because of cold starts, without evaluating the alternatives.

If VNet was your only reason, Flex Consumption now gives you VNet integration with scale-to-zero pricing. No need to pay $146/month for network access.

If your workload is sporadic (a few hundred invocations a day), the math doesn't work. That function costs pennies on Consumption. On Premium EP1, it costs $146/month regardless of usage. The cold start tax has to be genuinely painful to justify that gap.

And watch the SKU names. EP1 is Elastic Premium. P1v2 is a Dedicated App Service plan. They behave completely differently: EP1 scales dynamically based on event volume, P1v2 gives you a fixed VM that you scale manually. If your Terraform or Bicep has sku = "P1v2" and you expected autoscaling, check again.

Dedicated: fixed compute, fixed bill

The Dedicated plan runs your functions on a standard App Service plan. Same infrastructure, same pricing, same scaling model as a web app. Multiple function apps and web apps can share the same plan.

This is the plan you pick when you already have App Service infrastructure and want to add functions without creating a separate billing line item.

Pricing and compute

These are Windows pay-as-you-go prices for US East. Linux is cheaper (roughly 40-50% less for P-series tiers). P1v2 is a previous-generation SKU; Microsoft recommends P1v3 for new deployments.

Billing is hourly, prorated to the second, per scaled-out instance. Reserved instances (1-year or 3-year) can save up to 55% on Linux. The cost is fixed: you pay the same whether your functions execute zero times or a million times per day.

Scaling: you manage it

There is no event-driven scaling on Dedicated. The scale controller that powers Consumption and Premium does not apply here.

Your options:

Manual scale-out: set the instance count in the portal or via CLI
Rule-based autoscale (Standard tier and above): trigger scale-out based on CPU percentage, memory usage, or a schedule

Autoscale on App Service is slower than Premium's elastic scale. It reacts to sustained load patterns, not individual event bursts. App Service also has a newer "automatic scaling" feature for HTTP-based traffic, but it's not supported when Functions apps are in the plan.

Maximum instances: 10-30 per plan, or 100 in an App Service Environment (ASE).

Always On must be enabled in the App Service configuration. Without it, the Functions runtime goes idle after a period of inactivity. Unlike Consumption's scale-to-zero (which the platform manages), an idle Dedicated plan just means your functions silently stop processing. You're still billed for the compute.

When Dedicated fits

Dedicated makes sense in specific circumstances:

You already have an underutilized App Service plan. Adding functions to existing compute costs nothing extra. The plan is already paid for.
You run mixed workloads. A web app and a set of background processing functions on the same plan, sharing resources.
You need deployment slots. Up to 20, far more than Premium's 3.
Predictable billing matters more than efficiency. Some finance teams prefer a fixed monthly line item over variable serverless costs.

The downside is resource contention. If your web app and function app share an S1 instance and the web app spikes, your function throughput drops. There's no isolation within the plan.

Cold start mitigation: what to try first

If you're staying on Consumption or Flex Consumption, cold starts are part of the deal. The strategies below are ordered by impact, highest first. Not all of them apply to every plan.

1. ReadyToRun compilation

The single highest-impact change for .NET cold starts on Consumption and Flex Consumption. Two lines in your .csproj:

<PropertyGroup>
    <PublishReadyToRun>true</PublishReadyToRun>
    <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

ReadyToRun pre-compiles your assemblies to native code. The JIT compiler still runs for hot paths at runtime, but the initial load skips the bulk of compilation overhead. In practice, this cuts cold start time roughly in half.

The trade-off: your deployment package grows 2-3x because the assemblies contain both the native precompiled code and the original IL. For a typical Functions app, that's still well under the 1 GB deployment limit.

2. Placeholder optimization for .NET isolated

The Functions platform can pre-provision a worker process before your app code loads. Enable it with an app setting:

WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1

This requires .NET 6+, a 64-bit process, and the latest Azure Functions SDK versions. The placeholder worker starts the .NET runtime and gets the IPC channel ready while your code is still being loaded, shaving off part of the startup sequence.

Combine this with ReadyToRun for the best result on Consumption.

3. Trim your DI registrations

Every service you register in Program.cs adds to startup time. On a warm instance this is negligible. On a cold start, it compounds.

Register HTTP clients and SDK clients as singletons so they're constructed once and reused. Wrap expensive dependencies in Lazy<T> so they're only built when a function actually needs them:

builder.Services.AddSingleton(_ => new HttpClient(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2)
})
{
    BaseAddress = new Uri("https://api.example.com")
});

builder.Services.AddSingleton<Lazy<ExpensiveAnalyticsClient>>(sp =>
    new Lazy<ExpensiveAnalyticsClient>(() =>
    {
        var logger = sp.GetRequiredService<ILogger<ExpensiveAnalyticsClient>>();
        return new ExpensiveAnalyticsClient(logger);
    }));

The PooledConnectionLifetime on SocketsHttpHandler rotates DNS entries without disposing the HttpClient instance. This avoids socket exhaustion (the same problem IHttpClientFactory solves, but without requiring per-request factory calls in a singleton context).

Fewer functions per app also helps. Each function adds discovery and registration overhead at startup.

4. Warmup trigger (Premium and Flex Consumption only)

On plans that support prewarmed instances, the warmup trigger lets you run initialization code before the instance takes real traffic. Force-construct your lazy dependencies, open database connections, and send a throwaway HTTP request to prime the connection pool. See the Premium section above for the code.

The warmup trigger only fires during scale-out. It does not fire on restarts, deployments, or slot swaps. One per app, and the function must be named Warmup (case-insensitive).

What works where

Not every strategy applies to every plan:

On Dedicated with Always On enabled, cold start is largely a non-issue because instances stay running. On Premium, the always-ready and prewarmed instances handle most of it. ReadyToRun and DI trimming matter most on the serverless plans where instances start from scratch.

Choosing a plan: the decision matrix

Which plan for which workload

Consumption if your traffic is sporadic, you don't need VNet access, and your users can tolerate a few seconds of cold start. Timer triggers, low-volume queue processors, webhook receivers that aren't latency-sensitive. If your bill on Consumption is under $10/month, there's no reason to move.

Flex Consumption if you need VNet integration or more than 200 instances, but still want scale-to-zero pricing. Evaluate this before jumping to Premium. The always-ready instances give you a dial between pure serverless and always-warm, and you pay only for what you configure. The constraints (one app per plan, no deployment slots, Linux only) are the deciding factors.

Premium EP1 if your HTTP endpoints are latency-sensitive and cold starts are genuinely costing you users or revenue. Also the right choice for functions that run continuously or need more than 10 minutes of execution time. If you're running multiple function apps, a shared Premium plan can amortize the $146/month minimum across them.

Dedicated if you already have an App Service plan with spare capacity, need more than 3 deployment slots, or your finance team requires a fixed monthly line item. Don't create a Dedicated plan specifically for Functions unless you have a concrete reason: the lack of event-driven scaling makes it the least "serverless" option.

The mistake to avoid

The most common path is: start on Consumption, hit cold start problems in production, jump straight to Premium at $146/month. Flex Consumption sits between them and didn't exist when many teams made that decision. If you're evaluating today, Flex Consumption with 1-2 always-ready instances gives you warm starts with scale-to-zero pricing for on-demand instances. Test it before committing to Premium's minimum.

Are you running Consumption or Premium in production right now?

Azure Functions Beyond the Basics
Continues from Azure Functions for .NET Developers (Parts 1-9)

Part 1: Running Azure Functions in Docker: Why and How

Part 2: Docker Pitfalls I Hit (And How to Avoid Them)

Part 3: Scaling Azure Functions: Consumption vs Premium vs Dedicated (this article)

Docker Pitfalls I Hit (And How to Avoid Them)

Martin Oehlert — Fri, 24 Apr 2026 05:39:32 +0000

Your Dockerfile builds, your container starts, and your triggers never fire. The Functions host logs "no functions found" or the container sits idle, processing nothing. The gap between a working image and a working function app is entirely configuration. The runtime needs specific environment variables, the build must publish to the exact path the host expects, and Azurite connections behave differently inside a container network than on localhost. Four walls, four fixes. All code samples are in the companion repo.

Pitfall 1: Environment Variables That Vanish

Your container starts, the Functions host initializes, and the logs show this:

[2026-04-20T08:12:03Z] No job functions found. Try making your job classes and methods public.
[2026-04-20T08:12:03Z] If you're using binding extensions (e.g. Azure Storage, ServiceBus, Timers, etc.)
[2026-04-20T08:12:03Z] make sure you've called the registration method for the extension(s)
[2026-04-20T08:12:03Z] in your startup code
[2026-04-20T08:12:03Z] 0 functions loaded

You check your code. The classes are public. The methods are public. The bindings are registered. Everything runs fine with func start on your machine.

The error is misleading. The real cause: FUNCTIONS_WORKER_RUNTIME is not set.

Why the file you trusted does not exist here

local.settings.json is a dev-time convenience. The Azure Functions Core Tools reads it when you run func start locally. Inside a container, that file is never loaded. The container runtime reads OS environment variables only, and if FUNCTIONS_WORKER_RUNTIME is missing, the host cannot determine which language worker to start. It discovers zero functions and prints an error that sends you looking at your code instead of your configuration.

AzureWebJobsStorage is the second variable that catches people. Without it, you get a different failure:

Value cannot be null. (Parameter 'connectionString')

Or worse, no error at all. HTTP triggers still work because they do not require storage. You test with an HTTP endpoint, everything responds, you deploy, and your queue triggers silently never fire. The host needs a storage connection to manage leases, checkpoints, and timer schedules for every non-HTTP trigger type.

If you set FUNCTIONS_WORKER_RUNTIME to dotnet instead of dotnet-isolated, the host raises AZFD0013: the configured runtime does not match the worker runtime metadata in your published artifacts. Another error that points away from the actual one-word fix.

The second trap: `.env` files that silently mangle values

Azure Storage connection strings are long. If your .env file wraps them across lines, Docker Compose silently truncates or corrupts the value:

# Broken: line-wrapped connection string
AzureWebJobsStorage=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;
  AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;
  BlobEndpoint=http://azurite:10000/devstoreaccount1;
  QueueEndpoint=http://azurite:10001/devstoreaccount1;

# Working: entire value on one line
AzureWebJobsStorage=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite:10000/devstoreaccount1;QueueEndpoint=http://azurite:10001/devstoreaccount1;

No warning, no parse error. The value just stops at the first newline.

The fix: separate constants from secrets

Bake values that never change per environment into your Dockerfile:

ENV AzureWebJobsScriptRoot=/home/site/wwwroot
ENV FUNCTIONS_WORKER_RUNTIME=dotnet-isolated

Pass everything else through your Compose file or deployment config:

services:
  functions:
    build: .
    environment:
      - AzureWebJobsStorage=${AzureWebJobsStorage}
      - APPLICATIONINSIGHTS_CONNECTION_STRING=${APPLICATIONINSIGHTS_CONNECTION_STRING}
    env_file:
      - .env

Connection strings and instrumentation keys stay out of the image. They come from .env locally and from app settings or Key Vault references in production.

One more if you are deploying custom containers to App Service specifically: set WEBSITES_ENABLE_APP_SERVICE_STORAGE=false. The default (true) mounts persistent storage over /home, which overwrites your published function code at startup. This does not apply to Container Apps, only App Service (GitHub issue #642).

Pitfall 2: Azurite and Docker Networking

Most tutorials tell you to set AzureWebJobsStorage to UseDevelopmentStorage=true and move on. That shorthand expands to a full connection string pointing at localhost:

DefaultEndpointsProtocol=http;
AccountName=devstoreaccount1;
AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;
BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;
QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;
TableEndpoint=http://127.0.0.1:10002/devstoreaccount1;

See those 127.0.0.1 addresses? When Azurite runs on your machine, that works fine. Inside Docker, it breaks.

Each container runs in its own network namespace. 127.0.0.1 inside the functions container refers to the functions container itself, not Azurite. Your function tries to reach storage on its own loopback interface, finds nothing listening, and fails silently or throws a connection error depending on the trigger type.

Docker Compose creates a shared bridge network where each service name resolves to the corresponding container's IP. So the fix is to spell out the full connection string with the Compose service name replacing 127.0.0.1:

DefaultEndpointsProtocol=http;
AccountName=devstoreaccount1;
AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;
BlobEndpoint=http://azurite:10000/devstoreaccount1;
QueueEndpoint=http://azurite:10001/devstoreaccount1;
TableEndpoint=http://azurite:10002/devstoreaccount1;

azurite here is whatever you named the service in your docker-compose.yml. DNS resolution happens automatically on the Compose network.

But DNS resolving correctly is not enough. By default, Azurite binds to 127.0.0.1 inside its own container, which means it only accepts connections from itself. You need to pass --blobHost 0.0.0.0 --queueHost 0.0.0.0 --tableHost 0.0.0.0 so Azurite listens on all interfaces. Without this, the functions container resolves azurite to the right IP, opens a TCP connection, and gets "Connection refused."

This pitfall hides well because HTTP triggers don't need storage. You build a function app, add an HTTP trigger, test it in Docker, everything works. Then you add a queue trigger and it silently does nothing: no errors in the console, no messages processed, no indication that storage is unreachable. The function host quietly skips triggers it can't initialize.

A quick connectivity check saves you the debugging:

docker compose exec functions curl -s http://azurite:10000

If Azurite is reachable and bound correctly, you get back a short XML or text response. If you get "Connection refused," check the bind flags. If you get a DNS error, check your service name.

Part 1 already showed the working Compose file with these settings in place. That is why each piece is there.

Pitfall 3: Debugging a Silent Container

Your container starts, the health check passes, but nothing happens. No HTTP responses, no queue processing, no timer triggers. The logs show the host booting and then silence. This is the most common failure mode with Azure Functions in Docker, and it has six distinct causes. Work through them in order.

Step 1: Check if the host found your functions. Run docker logs <container> and look for the function discovery block near startup:

Host initialized (348ms)
Found the following functions:
  ProcessOrder: timerTrigger
  SubmitOrder: httpTrigger

If you see "Host initialized" but zero functions listed, your AzureWebJobsScriptRoot is wrong or your Dockerfile's WORKDIR does not point to /home/site/wwwroot. The host scans that directory for compiled function metadata. If it points somewhere else, it finds nothing and starts successfully with nothing to run. This is the root cause in #642 and #980.

Step 2: Check storage connectivity. If your functions are listed but triggers never fire, the problem is almost always storage. Look for this error in the logs:

The Azure Storage connection string named 'Storage' does not exist.

Timer triggers and queue triggers need a valid AzureWebJobsStorage connection to coordinate leases and checkpoints. HTTP triggers work without storage, so a container that responds to HTTP but ignores everything else is a storage configuration problem. Verify your environment variables:

docker compose exec functions env | grep FUNCTIONS

This surfaces FUNCTIONS_WORKER_RUNTIME, AzureWebJobsStorage, and any other Functions-specific configuration in the running container.

Step 3: Inspect the container filesystem. When functions still do not appear after fixing the script root, the published output may not be where you think it is. Check directly:

docker compose exec functions ls /home/site/wwwroot

You should see your .dll files, host.json, function.json files, and the worker.config.json. A wrong COPY --from=build path in a multi-stage Dockerfile is the most common cause: the build stage publishes to /app/publish but the copy targets /app/out, and the container starts with an empty wwwroot.

Step 4: Check for assembly conflicts. If the host discovers your functions but the worker crashes on invocation, look for FileNotFoundException referencing assemblies like System.Memory.Data. This happens when in-process WebJobs SDK packages ship inside an isolated worker image. The host and worker expect different assembly versions, and the loader fails silently until a trigger actually fires. Pin your NuGet package versions to match the host's expectations. See #1221 for the specific version matrix.

Step 5: Attach a debugger. When the logs tell you nothing useful, attach directly. VS Code's pipeTransport configuration or Rider's Docker attach both work. The critical detail: the Functions host and the isolated worker are separate .NET processes. The host is the parent process managing triggers; your code runs in the worker. Attach to the worker PID, not the host PID. If you attach to the host, you will see trigger infrastructure but none of your breakpoints will hit.

Step 6: Watch for broken image tags. Sometimes your container worked yesterday and fails today with no code changes. Base image tag updates can silently break functions. Tag 4.33.2 broke function discovery for days before anyone traced it back to the image itself (#1068). Always pin specific version tags in your Dockerfile. Never use :latest for the Functions base image in production.

Other Known Issues

A few problems fall outside the decision tree but will bite you eventually:

No graceful shutdown. The default entrypoint start.sh runs as PID 1 and does not forward SIGTERM to child processes. Your container gets SIGKILL after the orchestrator's grace period expires, which means in-flight executions are terminated without cleanup. This has been open for five years (#404). Workaround: use dumb-init or a custom entrypoint that traps signals.

Non-root containers break startup. The Functions host needs write access to /azure-functions-host at startup. Running the container as a non-root user fails unless you fix directory permissions in your Dockerfile (#424).

Development environment restart loops. Setting AZURE_FUNCTIONS_ENVIRONMENT=Development can trigger the host to restart repeatedly as it watches for file changes that never settle (#1207). Use Production or Staging in Docker unless you specifically need development-mode diagnostics.

Pitfall 4: Image Size and Cold Start

The default Azure Functions base image is 800-900 MB. Add your application code, NuGet packages, and assets, and you're over 1 GB before your first request arrives (#236).

The -slim tags can paradoxically be larger than the regular tags (#1230). Always verify with docker images.

Old extension bundles (v2 and v3) still ship inside the v4 images, wasting roughly 429 MB on code your app will never execute (#880).

Every optimization here is measurable. Start with docker images and track the delta.

.dockerignore

Without a .dockerignore, COPY . . sends your entire working directory to the Docker daemon, including .git/ history and local.settings.json (which contains connection strings and keys).

bin/
obj/
.git/
.vs/
.vscode/
local.settings.json
node_modules/
*.user
Dockerfile

This alone can cut your build context by hundreds of megabytes and prevent secrets from leaking into image layers.

Layer ordering for cache hits

The order of your COPY instructions determines whether Docker can reuse cached layers. Copy the project file first, restore, then copy everything else:

COPY MyFunctionApp.csproj .
RUN dotnet restore

COPY . .
RUN dotnet publish -c Release -o /home/site/wwwroot

When only source code changes, the restore layer stays cached:

Step 3/7 : RUN dotnet restore
 ---> Using cache
 ---> 4a8b2c1d3e5f
Step 4/7 : COPY . .
 ---> 9f1e2d3c4b5a

That "Using cache" line saves 30-120 seconds per build depending on your package count. Without this ordering, every code change re-downloads every NuGet package.

ReadyToRun compilation

Add the PublishReadyToRun flag to pre-compile IL to native code, reducing JIT time at startup:

RUN dotnet publish -c Release -o /home/site/wwwroot \
    -p:PublishReadyToRun=true

This increases image size slightly but cuts cold start latency by front-loading compilation to build time instead of request time.

Trimming (PublishTrimmed=true) is the more aggressive option. It strips unused assemblies and can dramatically reduce image size. But the Functions runtime uses reflection to discover your function endpoints, and the trimmer can remove types it considers unreachable. If your functions disappear after trimming, that's why. Use trimming only if you're willing to maintain trim annotations and test thoroughly.

Cold start: the numbers that matter

On Azure Container Apps, image pull time dominates cold start because the platform scales to zero:

Image size	Pull time	Total cold start
~480 MB	~20s	~25-30s
~140 MB	~7s	~12-15s

That 13-second pull difference hits every scale-from-zero event. On Functions Premium with always-ready instances, the image is cached on warm infrastructure, so size matters less for latency. It still matters for deployment speed and registry costs.

CVE accumulation

Base images are only rebuilt monthly, so vulnerabilities accumulate between rebuilds (#1185). A multi-stage build where you copy your published output onto a fresh OS base gives you control over patching:

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# ... build steps ...

FROM mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated8.0
COPY --from=build /home/site/wwwroot /home/site/wwwroot

Run docker images after applying these changes. A starting point of 1 GB+ dropping to 300-400 MB is typical when you combine layer optimization, proper .dockerignore, and ReadyToRun instead of carrying dead extension bundles.

Pre-Deploy Checklist

Save yourself a repeat debugging session. Run through this before every container deployment.

[ ] FUNCTIONS_WORKER_RUNTIME set to dotnet-isolated in your container environment, not inherited from local.settings.json
[ ] AzureWebJobsStorage uses explicit endpoint strings with Docker service names instead of UseDevelopmentStorage=true
[ ] Connection strings are single-line in .env files with no line-wrapping
[ ] docker logs confirms all expected functions discovered at startup
[ ] AzureWebJobsScriptRoot points to /home/site/wwwroot (verify if using a custom base image)
[ ] .dockerignore excludes bin/, obj/, .git/, and local.settings.json
[ ] NuGet restore layer cached separately from the source code copy step
[ ] Base image tag pinned to a specific version, not :latest
[ ] Azurite bound to 0.0.0.0 in your Compose configuration
[ ] Image tested with docker compose up locally before pushing to any registry

Which of these four pitfalls cost you the most debugging time: environment variables, Azurite networking, silent startup failures, or image size?

Azure Functions Beyond the Basics

Part 1: Running Azure Functions in Docker: Why and How

Part 2: Docker Pitfalls I Hit (And How to Avoid Them) (this article)

From AZ-204 to AI-200: What Changed and Why It Matters

Martin Oehlert — Fri, 17 Apr 2026 21:18:34 +0000

Comparing the AZ-204 skill outline against the AI-200 course structure, roughly 60% of AZ-204 carries forward, 25% is dropped entirely, and AI-200 adds about 30% net-new content that AZ-204 never touched. Which side of that split you land on determines whether this transition is a week of review or a month of study. The gap is lopsided enough that you cannot assume existing knowledge transfers cleanly.

What Is AI-200?

Full name: AI-200: Azure AI Cloud Developer Associate

Format: Multiple choice, case studies, and scenario-based questions. Based on standard Microsoft exam format: approximately 40-60 questions, 100-minute window, passing score around 700/1000.

Timeline:

Beta exam: April 2026
General availability: July 2026 (estimated)
AZ-204 retirement: July 31, 2026

Course: The AI-200T00 instructor-led training course maps to seven learning paths that define the exam scope:

Container Hosting: ACR, App Service containers, Container Apps, AKS
Cosmos DB: NoSQL API with vector search and AI integration
PostgreSQL Vector Search: pgvector, HNSW indexes, hybrid search
Azure Managed Redis: data operations, event messaging, vector storage
Backend Services: Service Bus, Event Grid, Azure Functions
Secrets and Configuration: Key Vault, managed identities, App Configuration
Observability: OpenTelemetry, Azure Monitor logs and metrics

What Carried Forward, What Got Dropped, What's New

Carried forward (~60% of AZ-204)

Most of the backend services survive: Azure Functions (triggers, bindings, Durable Functions), Service Bus, Event Grid, Key Vault, App Configuration, and managed identities all carry over. Several topics are expanded rather than simply retained. Container Apps now gets deeper coverage of KEDA scaling and Dapr integration. Cosmos DB adds vector search on top of the existing NoSQL API. Container Registry picks up ACR Tasks. And managed identities extend to AKS workload identity, which matters because AKS is one of the largest new additions. If you already hold AZ-204, this 60% is review, not new study.

Dropped (~25% of AZ-204)

Comparing the AZ-204 study guide against the AI-200 course outline, seven topics are gone entirely: Blob Storage SDK, MSAL/Identity Platform, Microsoft Graph, SAS tokens, API Management, Event Hubs, and Azure Container Instances. Microsoft removed the CRUD-oriented cloud app topics that do not serve AI workloads. You will not be tested on generating SAS tokens or calling Graph endpoints. If you spent weeks on MSAL token flows for AZ-204, that knowledge still applies to real projects, but it will not appear on AI-200.

Brand new (~30% of AI-200)

Based on the AI-200T00 course structure, AKS spans three modules and likely accounts for an estimated 20-25 exam questions. You need cluster creation with kubectl, ACR integration via --attach-acr, and scaling with HPA and cluster autoscaler. Configuration covers ConfigMaps, Secrets, Key Vault CSI Driver, persistent storage (Azure Disk for RWO, Azure Files for RWX), taints and tolerations, and the difference between resource requests and limits. Monitoring adds Container Insights, KQL queries for pod status and events, managed Prometheus, and alerting on OOMKills and resource exhaustion. This is the single largest new topic by question count.

PostgreSQL with pgvector is where AI-200 tests your understanding of vector databases, covering an estimated 8-11 questions across three modules. The foundation is Flexible Server provisioning with Entra ID auth and PgBouncer connection pooling. From there, you enable the pgvector extension for vector storage and work with distance operators: L2 (<->), cosine (<=>), and inner product (<#>). Batch embedding pipelines use Azure OpenAI to generate vectors at scale. Index optimization is where it gets specific: IVFFlat (partition-based, best under 100K vectors with frequent updates) versus HNSW (graph-based, best above 500K static vectors). Hybrid search combines vector similarity with metadata filters using standard WHERE clauses.

Azure Managed Redis replaces the narrow "Azure Cache for Redis" coverage from AZ-204 with a broader scope across an estimated 7-12 questions. Five core data types (strings, hashes, lists, sets, sorted sets) and caching patterns (cache-aside, write-through, write-behind) form the baseline. The exam also tests event messaging: Pub/Sub for fire-and-forget broadcasting versus Streams for durable at-least-once delivery with consumer groups (XREADGROUP, XACK). On the Enterprise tier, RediSearch enables vector similarity search using FLAT and HNSW indexes combined with tag, numeric, and text filters.

OpenTelemetry rounds out the new content with an estimated 5-7 questions. The Azure Monitor OpenTelemetry Distro provides a one-line setup via UseAzureMonitor(), replacing the proprietary Application Insights SDK. Custom spans use ActivitySource, custom metrics use Meter instruments, and W3C TraceContext propagation handles distributed trace correlation across services. Sampling strategies control telemetry volume and cost, which is the kind of production concern the exam now prioritizes.

Three Shifts Worth Understanding

The topic changes above are not random. They reflect a different definition of what an Azure developer does.

Vector databases replace blob storage

If your application retrieves context from a knowledge base before passing it to a language model, you are building a RAG pipeline, and the retrieval layer runs on one of three backends the exam now tests.

Cosmos DB supports vector search for globally distributed workloads. PostgreSQL with pgvector handles complex hybrid queries where you combine vector similarity with metadata filters in standard WHERE clauses. Redis provides low-latency vector retrieval on the Enterprise tier using FLAT and HNSW indexes. Each backend has different index types (IVFFlat, HNSW, FLAT), different distance operators, and different tradeoffs around dataset size and query complexity.

AZ-204 treated storage as a CRUD problem: upload blobs, set access tiers, generate SAS tokens. AI-200 treats storage as a search problem, and the skill gap between "call a PUT endpoint" and "choose the right index type for 500K embeddings" is not small.

AKS moves from infrastructure to developer concern

AI workloads need GPU-enabled nodes isolated from general compute, custom operators, and fine-grained resource limits. Container Apps cannot give you any of that. AI-200 assigns three full modules to AKS: deployment, configuration, and monitoring.

The exam expects you to select between Azure Disk (RWO) and Azure Files (RWX) storage classes, integrate secrets through the Key Vault CSI Driver, and manage node pools with taints and tolerations. Monitoring means writing KQL queries against Container Insights to diagnose pod failures and resource exhaustion. AZ-204 kept you at the Container Apps level, where Kubernetes was an implementation detail you never touched. That abstraction no longer holds when your inference service needs a dedicated A100 node pool with specific resource requests and limits.

OpenTelemetry replaces proprietary instrumentation

Your tracing code now works the same whether telemetry flows to Azure Monitor, Jaeger, or Datadog. The Application Insights SDK locked you into Microsoft's instrumentation API, Microsoft's backend, and Microsoft's query tools. AI-200 replaces that instrumentation layer with OpenTelemetry, the CNCF-backed open standard.

The Azure Monitor OpenTelemetry Distro makes setup a one-liner with UseAzureMonitor(), but the exam goes deeper. Custom instrumentation means creating spans with ActivitySource and recording metrics with Meter instruments. Distributed trace correlation relies on W3C TraceContext headers propagated across service boundaries. Sampling configuration controls telemetry volume, which directly affects cost at scale. Azure Monitor still serves as the analysis backend; what changed is the instrumentation contract.

What This Means for Your Study Plan

If you already hold AZ-204: roughly 60% carries forward. Your knowledge of Azure Functions, Service Bus, Event Grid, Key Vault, managed identities, and Cosmos DB basics is still valid. The gap areas are AKS (the largest single investment if you have not worked with Kubernetes), PostgreSQL with pgvector, Azure Managed Redis vector storage and Streams, and OpenTelemetry custom instrumentation. Budget 3-4 weeks of focused study on those new topics, then 1 week reviewing carried-over material to make sure nothing has shifted in scope.

If you are currently studying for AZ-204: you have a decision to make before July 31, 2026. If you are close to passing, finish it: the credential stays valid through its full renewal cycle. If you are early in your studies, pivot to AI-200 now and skip the dropped topics entirely. There is no reason to invest time in the Blob Storage SDK, MSAL, Microsoft Graph, API Management, or Event Hubs when those topics will not appear on the replacement exam.

If you are starting fresh: go directly to AI-200. The AI-200T00 course structure and Microsoft Learn paths give you everything you need; AZ-204 material adds no value at this point.

The 8-week plan below assumes you are starting from scratch or pivoting from early AZ-204 study:

The AI-200T00 course and the Microsoft Learn paths aligned to each domain are the primary resources once they publish alongside the beta exam. Are you finishing AZ-204 before July or pivoting to AI-200 now?

DEV Community: Martin Oehlert

Human Interaction and External Events: Approval Workflows

WaitForExternalEvent pattern

Approval endpoint design

Timeout and escalation

Instance ID storage patterns

Wrapping up

Fan-Out/Fan-In and the Async HTTP Pattern

When sequential processing isn't enough

Fan-out/fan-in with Task.WhenAll

The loop mistake (and the fix)

The async HTTP pattern

Memory and concurrency limits

Closing

Intro to Durable Functions: Orchestrations and the Chaining Pattern

Why a stateless function can't run a workflow

The three roles: orchestrator, activity, client

The chaining pattern

Replay mechanics

Determinism rules

When to use Durable Functions vs queues

What's next

Deploying .NET Aspire Apps to Azure: AZD, ACA, and What Aspire Generates

From local to Azure

The AZD workflow

What Aspire generates

Where the generated happy path stops: wiring Functions triggers

Owning the infrastructure

GitHub Actions CI/CD

Closing

Azure Services as Aspire Resources: Service Bus, Storage, and Redis

The connection string problem, widened

Service Bus as an Aspire resource

Storage beyond host storage

Redis as an Aspire resource

How Aspire resolves dev versus production

Three resources, one source of truth

Getting Started with .NET Aspire for Azure Functions

The drift surface

Why Aspire, and why for Functions

The AppHost as composition root

The Functions app as an Aspire resource

How Aspire starts the worker

Service discovery: two cases

What the worker actually receives

The one change inside the Functions project

The dashboard

Before and after

Honest scope

Still copying local.settings.json.example, or moved to an AppHost?

Preparing for Migration: Decoupling Your Function Logic

The trigger as a thin controller

Before: the trigger doing too much

After: the contract in code

What does not belong, with evidence from the sample

Why thinness matters when the host changes

Abstracting Azure SDK dependencies

Infrastructure clients live above Settlement.Core

The Functions host does not call AddAzureClients

Building portable service classes

Rule 1: zero references to Microsoft.Azure.Functions.* in the project file

Rule 2: configuration via IOptions<T> with validated binding

Rule 3: logging via ILogger<T>

The BackgroundService lifetime trap

Testing without the Functions runtime

Integration tests at the same boundary

The smoke test that earns its keep

Before and after: a refactoring walkthrough

Series wrap-up: where to go from here

Closing question

When Azure Functions Fight Back: Signs You've Outgrown Them

Performance walls you will hit

Execution timeout per plan

The fix that lets you stay (when it can)

Memory ceilings

SNAT ports and connection exhaustion

Database connections do not get the same fix

Local file system

Complexity signals that indicate a problem

Durable Functions sub-orchestration sprawl

Infrastructure clients live above `Settlement.Core`

The Functions host does not call `AddAzureClients`

Rule 1: zero references to `Microsoft.Azure.Functions.*` in the project file

Rule 2: configuration via `IOptions<T>` with validated binding

Rule 3: logging via `ILogger<T>`

The `BackgroundService` lifetime trap

The second trap: `.env` files that silently mangle values