DEV Community: Martin Oehlert

Scaling Azure Functions: Consumption vs Premium vs Dedicated

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

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?

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:

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?

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?

Running Azure Functions in Docker: Why and How

Martin Oehlert — Fri, 17 Apr 2026 05:23:51 +0000

When zip-deploy stops fitting

Your Azure Function needs to generate PDF invoices, so you add Puppeteer to your project. Zip-deploy works fine on your machine, but the Consumption plan doesn't have the Chromium dependencies installed. The function throws a cryptic error about missing shared libraries, and you're stuck choosing between a workaround that limits your architecture or a deployment model that gives you full control over the OS.

Most Azure Functions never hit this wall. Zip-deploy and run-from-package handle the majority of workloads well: your code and dependencies get packaged, uploaded, and run on Microsoft's managed infrastructure. You don't think about the OS, the runtime image, or what's installed underneath. That's the point, and it's a good default.

Containerizing a Function adds real operational cost. You own the base image, the patching cycle, the registry, and the build pipeline. If zip-deploy already works, containerizing your Function adds overhead with no payoff.

But there are specific problems where Docker earns that overhead back.

Native dependencies are the most common trigger. FFmpeg for media processing, Puppeteer or Playwright for headless browser work, libgdiplus for image manipulation: these require OS-level packages that the default Azure Functions host doesn't include. A custom Docker image lets you install exactly what the function needs.

Reproducible builds across environments matter when your team needs the same OS, the same SDK version, and the same native tooling from local dev through staging to production. A Dockerfile pins all of it in version control.

Running Functions alongside other containers is the third case. If you're already deploying to Azure Container Apps or AKS, packaging your Function as a container lets it sit next to your APIs, workers, and sidecars in the same orchestration layer. One deployment model, one scaling configuration, one set of infrastructure to manage.

If one of those three problems is yours, the container tax is worth paying.

The Dockerfile: multi-stage build for .NET 10

Start with the complete Dockerfile, then walk through what each stage does.

FROM --platform=linux/amd64 mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY *.csproj .
RUN dotnet restore

COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM --platform=linux/amd64 mcr.microsoft.com/azure-functions/dotnet-isolated:4-dotnet-isolated10.0 AS runtime
WORKDIR /home/site/wwwroot
COPY --from=build /app/publish .

Fourteen lines. That's the whole thing.

The --platform=linux/amd64 flag on both FROM lines pins the image architecture. The Azure Functions base images only ship for linux/amd64, so without this flag, builds on Apple Silicon pull the wrong manifest and fail. Pinning the platform makes the Dockerfile work identically on Intel and ARM machines.

The build stage uses the .NET 10 SDK image to compile your project. The COPY *.csproj then dotnet restore pattern caches NuGet packages in a Docker layer, so subsequent builds skip the restore unless your dependencies change. The dotnet publish step compiles your code and produces a deployment-ready output in /app/publish.

The runtime stage switches to the Azure Functions base image. This image ships with the Functions host process, the dotnet-isolated worker runtime, and the three environment variables your app needs:

AzureWebJobsScriptRoot=/home/site/wwwroot
FUNCTIONS_WORKER_RUNTIME=dotnet-isolated
AzureFunctionsJobHost__Logging__Console__IsEnabled=true

You don't need to set any of these yourself. The base image handles it. Your only job is to place the published output at /home/site/wwwroot, which is why WORKDIR must point there. Get that path wrong and the Functions host starts but finds zero functions.

The final COPY --from=build pulls the compiled output from the build stage into the runtime image, keeping the SDK and all intermediate build artifacts out of your production container.

What you should know before building

Pin your SDK version in global.json. The base image 4-dotnet-isolated10.0 bundles a specific .NET 10 runtime. If your local SDK rolls ahead of what the image ships, subtle mismatches at runtime can show up. Pinning keeps builds deterministic across laptops, CI, and the image:

{
  "sdk": {
    "version": "10.0.201",
    "rollForward": "latestPatch"
  }
}

Package version floor for .NET 10. The isolated worker packages below 2.x don't target .NET 10. You need at minimum:

Microsoft.Azure.Functions.Worker 2.50.0 or later
Microsoft.Azure.Functions.Worker.Sdk 2.0.5 or later

If you're upgrading an existing project from .NET 8, bumping just the TargetFramework without updating these two packages is the most common failure mode.

.NET 10 doesn't run on the Linux Consumption plan. This is a hard platform constraint, not a preview gap. If your current app runs on Linux Consumption and you want .NET 10, you need to migrate to the Flex Consumption plan first. Premium, ACA, and AKS (covered later) all support .NET 10 without this restriction.

The Functions host runs on .NET 8 internally. Even in the dotnet-isolated10.0 image, the host process itself targets .NET 8. Your worker process runs on .NET 10. This is expected behavior for the isolated model, not a bug: the two processes communicate over gRPC, so the runtime versions are independent.

These images are linux/amd64 only. If you're on Apple Silicon, Docker Desktop runs them under Rosetta or QEMU emulation. Builds work fine. Performance is noticeably slower than native ARM execution, so keep local integration test suites short.

No slim variant exists for .NET 10 yet. The base image is Ubuntu-based (the .NET 10 container images moved from Debian to Ubuntu), and the full image weighs roughly 1.5 GB. A Mariner-based or distroless option may come later, but as of April 2026, this is what ships.

You own base image updates. Microsoft publishes monthly security patches to the base images, but unlike managed Functions deployments, custom containers do not auto-update. You pull the latest tag, rebuild, and redeploy. Set a calendar reminder or wire it into your CI pipeline. The official docs are explicit about this: maintaining your container is your responsibility.

Local development with Docker Compose and Azurite

Your function app needs storage. Timer triggers use it for lease management, queue triggers read from it directly, and durable functions store orchestration state there. In production that's an Azure Storage account. Locally, you need Azurite, Microsoft's storage emulator, running alongside your function container.

Here's the full Docker Compose file:

services:
  azurite:
    image: mcr.microsoft.com/azure-storage/azurite
    command: >-
      azurite
      --blobHost 0.0.0.0
      --queueHost 0.0.0.0
      --tableHost 0.0.0.0
      --loose
      --skipApiVersionCheck
    ports:
      - "10000:10000"
      - "10001:10001"
      - "10002:10002"
    volumes:
      - azurite-data:/data
    healthcheck:
      test: nc -z 127.0.0.1 10000
      interval: 3s
      retries: 5
      start_period: 5s

  functions:
    build: .
    ports:
      - "8080:80"
    environment:
      - AzureWebJobsStorage=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite:10000/devstoreaccount1;QueueEndpoint=http://azurite:10001/devstoreaccount1;TableEndpoint=http://azurite:10002/devstoreaccount1
    depends_on:
      azurite:
        condition: service_healthy

volumes:
  azurite-data:

The --blobHost 0.0.0.0 flags (and their queue/table equivalents) tell Azurite to listen on all network interfaces, not just localhost. Without them, your function container can't reach Azurite across the Docker network. --loose relaxes strict API validation. --skipApiVersionCheck prevents version mismatch errors when the Functions runtime targets a newer Storage API than Azurite supports.

The named volume azurite-data keeps your storage data intact between docker compose down and docker compose up. Queue messages, blob uploads, table entities: all survive restarts. Drop the volume only when you want a clean slate (docker compose down -v).

The health check deserves attention. Without it, Docker starts both containers simultaneously. Your function app boots in seconds, tries to connect to Azurite, and fails because Azurite hasn't finished initializing. The nc -z 127.0.0.1 10000 check confirms Azurite is actually accepting connections before the function container starts.

Now for the part that will cost you an hour if you don't know about it.

Your first instinct for the storage connection string will be UseDevelopmentStorage=true. That's what every Azure Functions tutorial uses, and it works fine when Azurite runs on your host machine. Inside Docker, it breaks. The shorthand expands to endpoints pointing at 127.0.0.1, which inside the function container means "myself," not "the Azurite container next door."

The fix is the explicit connection string you see in the Compose file above. The critical difference: every endpoint URL uses azurite as the hostname (the Compose service name) instead of 127.0.0.1. Docker's internal DNS resolves azurite to the correct container IP automatically. The account name and key are Azurite's well-known development credentials, the same ones UseDevelopmentStorage=true uses under the hood.

One practical tip: that connection string is long and ugly. Don't try to split it across multiple lines in your Compose file or inject it from a .env file with line breaks. YAML will quietly mangle it. Keep it on a single line, or use a .env file with the entire value on one line and reference it with ${AzureWebJobsStorage} in your Compose file.

Run docker compose up --build and you should see Azurite report all three services listening, followed by your function app discovering its triggers. If the function container restarts in a loop, check the connection string first. Nine times out of ten, that's the problem.

Debugging in containers: VS Code and Rider

Add a debug stage to your Dockerfile that installs the .NET debugger:

FROM build AS debug
RUN dotnet tool install --tool-path /tools dotnet-dump
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl unzip procps \
    && curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

ENV DOTNET_USE_POLLING_FILE_WATCHER=1
ENTRYPOINT ["dotnet", "run", "--project", "/src/HttpTriggerDemo"]

The DOTNET_USE_POLLING_FILE_WATCHER environment variable is required because Docker volume mounts don't support inotify. Without it, file change detection silently fails.

VS Code with pipeTransport

Point your launch.json at the container using pipeTransport instead of opening a debug port:

{
  "name": "Attach to Docker",
  "type": "coreclr",
  "request": "attach",
  "processId": "${command:pickRemoteProcess}",
  "pipeTransport": {
    "pipeProgram": "docker",
    "pipeArgs": ["exec", "-i", "my-functions-debug"],
    "debuggerPath": "/vsdbg/vsdbg",
    "pipeCwd": "${workspaceFolder}"
  },
  "sourceFileMap": {
    "/src": "${workspaceFolder}"
  }
}

pipeTransport sends debug commands through docker exec, so you never expose a debug port. The sourceFileMap entry maps the container's /src path back to your workspace so breakpoints resolve correctly. Start the container, hit F5 in VS Code, pick the dotnet process, and you're attached.

Rider

Rider handles most of this automatically. Open Run > Attach to Process, select the Docker tab, and pick your container. Rider installs its own debug agent on first attach. If you use Docker Compose, Rider also supports a native Docker Compose run configuration that builds, starts, and attaches in one step.

Docker Compose debug profile

Separate your debug configuration using a Compose profile so it doesn't interfere with production builds:

services:
  functions-debug:
    build:
      context: .
      target: debug
    volumes:
      - ./src:/src
    environment:
      - DOTNET_USE_POLLING_FILE_WATCHER=1
      - AzureWebJobsStorage=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite:10000/devstoreaccount1;QueueEndpoint=http://azurite:10001/devstoreaccount1;TableEndpoint=http://azurite:10002/devstoreaccount1
    depends_on:
      - azurite
    profiles: [debug]

Run it with docker compose --profile debug up. The target: debug directive tells Compose to stop at your debug stage, which includes the SDK and vsdbg but skips the production publish step.

Hot reload: set expectations

Using dotnet watch to wrap func start inside the container works, but every code change triggers a full restart. Expect 4-6 second cycles. That's usable for occasional debugging sessions, not for rapid iteration.

The pragmatic split: run func start on your host machine for day-to-day development. Keep Azurite and any dependencies (Service Bus emulator, CosmosDB emulator) in Docker. Reserve full-container debugging for integration testing or reproducing environment-specific issues. You get fast inner-loop feedback without giving up the production-parity benefits of containerized dependencies.

Where to deploy: ACA vs Premium vs AKS

You have a containerized Function. Now you need somewhere to run it. Three options exist, and each makes a different trade-off between operational control and managed convenience.

Azure Container Apps (ACA)

ACA is the recommended default for containerized Azure Functions. The platform reads your Function triggers and configures KEDA scaling rules automatically, so you never write ScaledObject YAML yourself.

Deploy with the Azure CLI:

az containerapp create \
  --name my-functions \
  --resource-group my-rg \
  --environment my-env \
  --image myregistry.azurecr.io/my-functions:latest \
  --registry-server myregistry.azurecr.io \
  --ingress external --target-port 80 \
  --min-replicas 0 \
  --max-replicas 30

Set --min-replicas 0 and your app scales to zero when idle, meaning zero compute cost during quiet periods.

Pricing follows the Container Apps model. On the Consumption plan, you pay per vCPU-second and GiB-second, with a monthly free grant of 180,000 vCPU-seconds and 360,000 GiB-seconds per subscription. For a Function that processes a few thousand events per day and idles overnight, you could land under $5/month. Dedicated workload profiles are available if you need guaranteed compute or GPU access, billed per instance rather than per resource consumed.

Cold start is the main gotcha. When your app scales from zero, the platform needs to pull the container image, provision resources, and start the Functions host. For a typical .NET isolated Function, teams commonly report 5-15 seconds on the first request after an idle period (Microsoft doesn't publish official cold start numbers). You can eliminate this by setting --min-replicas 1, but that means you pay for at least one instance around the clock. Keeping your container image small (pin to a specific tag, avoid unnecessary layers) helps reduce cold start time.

What ACA does not support: deployment slots, Functions access keys via the portal, and Functions proxies. If you rely on staging slots for zero-downtime swaps, you'll need to use ACA's built-in blue-green deployment with traffic splitting instead.

Azure Functions Premium Plan

The Premium plan (Elastic Premium, SKUs starting with EP) is the original way to run custom containers in Azure Functions. It predates ACA and still has one killer feature: always-ready instances with prewarmed buffers.

az functionapp plan create \
  --resource-group my-rg \
  --name my-premium-plan \
  --location eastus \
  --sku EP1 \
  --is-linux

az functionapp create \
  --resource-group my-rg \
  --plan my-premium-plan \
  --name my-functions \
  --deployment-container-image-name myregistry.azurecr.io/my-functions:latest

Three SKU sizes are available:

The billing model is the critical difference from ACA. Premium plan charges per core-second and memory across all allocated instances, with no execution charge. At least one instance must always be running. An EP1 instance running 24/7 costs roughly $155-175/month (varies by region). You cannot scale to zero. That always-on instance is the price you pay for eliminating cold starts entirely.

Where the Premium plan shines is latency-sensitive HTTP traffic. When load spikes, prewarmed instances are already initialized and waiting. No container pull, no cold start. For Functions that must respond in under 200ms consistently, this matters.

Watch out for the SKU naming confusion. EP1 is Elastic Premium (dynamic scaling). P1V2 is a Dedicated App Service plan (no dynamic scaling). Pick the wrong one and you'll pay more for less flexibility.

Maximum scale-out is up to 100 instances. The default maximumElasticWorkerCount in ARM templates is 20, so you may need to raise that limit explicitly.

AKS with KEDA

If your team already operates a Kubernetes cluster, running Functions there avoids introducing a new compute platform. You install KEDA as an AKS add-on, deploy your Function container as a standard Kubernetes deployment, and KEDA handles scaling based on event triggers.

apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: my-functions-scaler
spec:
  scaleTargetRef:
    name: my-functions
  minReplicaCount: 0
  maxReplicaCount: 50
  triggers:
    - type: azure-servicebus
      metadata:
        queueName: orders
        messageCount: "5"
      authenticationRef:
        name: servicebus-auth

KEDA supports these Azure Functions triggers directly: Azure Storage Queues, Azure Service Bus, Azure Event Hubs / IoT Hubs, Apache Kafka, and RabbitMQ. HTTP triggers work, but KEDA does not manage them directly; you configure HTTP scaling through the Horizontal Pod Autoscaler or Container Apps' HTTP scaler instead.

This is the only option that is community-supported, not Microsoft-supported. The docs are explicit: "Best-effort support is provided by contributors and from the community." If something breaks at 2am, you're opening a GitHub issue, not filing a support ticket. You also own the full Kubernetes stack: node pools, networking, RBAC, upgrades, monitoring.

Cost depends entirely on your cluster. If you're already paying for AKS nodes, adding a Function container is effectively free at the compute layer. If you'd be spinning up a new cluster just for Functions, the minimum AKS cost (one node with a Standard_D2s_v3 VM) starts around $70/month before you've deployed anything. KEDA itself is free and runs as a lightweight deployment in your cluster.

Cold start on AKS matches whatever your cluster can provision. With KEDA's scale-to-zero, a cold start involves scheduling a pod, pulling the image (if not cached), and starting the container. On a warm cluster with cached images, that's 3-10 seconds. On a cluster that needs to scale up a node, it could be 2-4 minutes.

Trade-offs at a glance

The decision tree is short. If you don't already run Kubernetes, don't start now for a single Function app. If your Function handles latency-sensitive HTTP requests and cold starts are unacceptable, use the Premium plan and accept the always-on cost. For everything else, ACA with the Consumption plan gives you scale-to-zero, automatic KEDA configuration, and the lowest operational overhead.

When Docker adds value

The deployment choice assumes the container was worth building in the first place. Every custom container you ship is infrastructure you now own: a registry to manage, a base image to patch monthly, a CI pipeline stage that didn't exist before. Zip-deploy skips all of that. Microsoft patches the managed host, and you never think about it.

That trade-off only flips when the managed host can't do what your function requires. Puppeteer needs Chromium installed at the OS level. Your compliance team mandates identical images from laptop to production. Your platform team already runs everything on AKS and adding a second deployment model would create more problems than it solves. Those are real constraints, not preferences.

The setup cost is lower than it looks. Twelve lines of Dockerfile, a Compose file with Azurite, and one container image that deploys to ACA, Premium, or AKS without changes. The ongoing cost is the part that matters: monthly base image pulls, rebuild-and-redeploy cycles, and one more thing to monitor.

Is your function broken without OS-level control, or would zip-deploy work fine if you tried it first?

Production Realities: When Azure Functions Stops Being Serverless

Martin Oehlert — Fri, 10 Apr 2026 05:38:43 +0000

The Enterprise Reality Check

At what point does an Azure Functions deployment stop being serverless and start being managed compute with a monthly bill? The shift happens not in one decision but in a sequence of reasonable ones: a VNet requirement from the security team, then private endpoints for the storage account, then an API gateway because the function is public-facing.

Your function works on Consumption. Zero cost at idle, automatic scaling, no infrastructure to think about. Then the security review lands. VNet integration is mandatory. Consumption doesn't support VNets, so you move to Flex Consumption. Private endpoints? Flex handles those too. You're still paying close to nothing at idle.

Then the surrounding infrastructure arrives. API Management adds $147 to $700. WAF protection adds $333. Each requirement passes its own cost-benefit test. None of them would make you question the architecture on their own. But the total floor lands somewhere between $530 and $1,080 per month, and the function plan itself is the smallest line item on the invoice.

The serverless pitch from Part 1 of this series was real. It just applies to a narrower set of workloads than most teams expect when they start. Once you're past that boundary, the question isn't whether to pay more. It's whether the Functions abstraction is still worth paying for, or whether Container Apps or App Service would give you the same outcome with less friction.

VNet: The Requirement That Changes Everything

Most enterprise environments mandate VNet integration for anything touching internal databases, key vaults behind private endpoints, or services that shouldn't be exposed to the public internet. The Consumption plan doesn't support VNet. That single requirement forces you into a different hosting plan, and each plan carries different pricing and operational constraints.

These are your options (East US pricing, April 2026):

Plan	VNet	Scale to Zero	Min Idle Cost/mo
Consumption	No	Yes	$0
Flex Consumption (on-demand)	Yes	Yes	$0
Flex Consumption (1 always-ready, 2 GB)	Yes	No	~$21
Premium EP1	Yes	No	~$146
Premium EP2	Yes	No	~$291
Dedicated S1/P1v3	Yes	No	varies
Container Apps (1 replica, 0.25 vCPU)	Yes	Yes	~$10

The jump from Consumption to Premium EP1 is $146/month for a single function app sitting idle. That's the cost of VNet access before your code processes a single request. Premium EP2 doubles it. These aren't theoretical numbers: they're the minimum monthly charges while your function waits for traffic.

Flex Consumption went GA in November 2024, and Microsoft now positions it as the recommended path for apps that need dynamic scaling with VNet support. In on-demand mode, Flex preserves the scale-to-zero model that made Consumption attractive. It also skips the Azure Files dependency (the shared file system Premium uses for deployment artifacts and runtime state). If your security team mandates private networking for storage, that saves roughly $30/month on private endpoint costs you'd otherwise pay on Premium. Under the hood, Flex uses shared gateways (up to 27 shared gateway IPs) instead of dedicated VNet-injected workers. That's how it keeps costs lower.

If you need guaranteed warm instances to avoid cold starts, Flex's always-ready configuration starts at about $21/month for one instance with 2 GB memory. That's still a fraction of Premium EP1.

But Flex has real constraints. Before you commit to it, compare what you're giving up:

Constraint	Flex Consumption	Premium
OS	Linux only	Windows + Linux
Apps per plan	One	Multiple
Deployment slots	Not supported	Up to 3
In-process .NET	Not supported	Supported
App init timeout	Fixed 30s	No limit
NFS file shares	No	Yes
Regional availability	Limited	Broad

The one-app-per-plan limitation is easy to overlook. You can't consolidate multiple function apps onto a single Flex plan the way you would with Premium. For teams running five or ten function apps, Premium's ability to share a single plan across all of them can actually cost less per app than running each on its own Flex instance.

The 30-second app init timeout is fixed. Not configurable. If your function app loads large dependency injection containers and connects to multiple databases at startup, 30 seconds may not be enough. Premium has no startup timeout limit, so heavy initialization is never a problem there.

If your codebase uses in-process .NET (the older hosting model where your function runs inside the Functions host process), Flex doesn't support it. You'd need to migrate to the isolated worker model first, which is its own project.

If you need Windows, deployment slots, or in-process .NET: Premium is your only option. If you're on Linux with the isolated worker model and can live with one app per plan, Flex Consumption gives you VNet support without abandoning scale-to-zero.

One more thing worth knowing: Linux Consumption is on a deprecation path. No new features after September 2025, with retirement scheduled for September 2028. Microsoft is pushing new workloads toward Flex Consumption, and the deprecation timeline makes that push harder to ignore.

The Plan Escalation Path

You start on Consumption. Your function triggers on an HTTP request, processes a message, writes to Cosmos DB. It costs nothing when idle. The serverless model, doing what it's supposed to do.

Then the requirements start arriving, one at a time.

VNet integration

Your security team requires all compute to run inside a virtual network. Consumption doesn't support VNet integration, so you move to Flex Consumption (on-demand only). This still scales to zero. You're still paying nothing at idle. No problem.

Running total: $0/mo idle

Private endpoints

Next review: inbound traffic to your function app must go through a private endpoint, and the backing storage accounts need private endpoints too.

Flex Consumption supports inbound private endpoints. You don't need to leave Flex for this. Your function app keeps scale-to-zero, and the private endpoint adds ~$7/month.

Flex also needs private endpoints for its backing storage accounts: Blob, Queue, and Table. Three endpoints, not four, because Flex has no Azure Files dependency. That's ~$22/mo for storage endpoints.

One deployment gotcha worth knowing: combining VNet integration with inbound private endpoints on Flex can cause deployment timeouts at the Kudu RemoveWorkersStep. The current workaround is temporarily removing the private endpoint during deployments, then re-adding it. Not ideal for automated pipelines, and worth factoring into your CI/CD design.

Running total: ~$29/mo (Flex on-demand)

The fork: when Premium becomes unavoidable

Most teams can stay on Flex through the VNet and private endpoint requirements. But Flex has constraints that force some teams onto Premium EP1:

Windows hosting required
Deployment slots for blue-green deployments
In-process .NET (not yet migrated to isolated worker)
Multiple function apps sharing a single plan
App init exceeding 30 seconds (Flex's hard timeout)

If any of these apply, EP1 gives you 1 vCPU and 3.5 GB of memory. The math: 1 vCPU at $116.80 plus 3.5 GB at $8.322 per GB = ~$146/mo. It runs 24/7 whether your function executes or not. Storage private endpoints on Premium cost ~$30/mo (four endpoints, including Azure Files).

Running total if forced to Premium: ~$176/mo

Cold starts

On Flex, cold starts are still possible when scaling from zero. If your workload needs guaranteed warm instances, Flex's always-ready configuration starts at ~$21/month for one instance with 2 GB memory. On Premium, cold starts are a non-issue: EP1 keeps at least one instance warm by default.

Running total: ~$50/mo (Flex + always-ready) or ~$176/mo (Premium)

API Management

Your API needs rate limiting and a developer portal. You add Azure API Management. The pricing depends on what your organization needs:

APIM Basic (classic): ~$147/mo, no VNet integration, 99.95% SLA
APIM Standard v2: ~$700/mo, partial VNet support (backend only), 99.95% SLA
APIM Premium (classic): ~$2,795/mo, full VNet integration, 99.99% SLA

Most teams start with Basic and accept the VNet gap. Some compliance requirements force Standard v2 or higher.

Running total: ~$197/mo (Flex + Basic) or ~$323/mo (Premium + Basic)

WAF protection

Compliance also wants a Web Application Firewall in front of your API. You deploy Application Gateway WAF_v2.

The breakdown: $0.443/hour for 730 hours ($323), plus at least one capacity unit ($10.50), plus a public IP ($3.65). That's ~$333-335/mo.

Application Gateway v1 retires April 28, 2026, so WAF_v2 is the only option going forward.

Running total: ~$530/mo (Flex floor) or ~$656/mo (Premium floor)

The full picture

Consumption ($0 idle)
  + VNet requirement
  → Flex on-demand: still $0 idle

  + private endpoints (inbound + storage)
  → Flex: ~$29/mo (1 inbound PE + 3 storage PEs)
  → Premium (if forced by constraints): ~$176/mo (EP1 + 4 storage PEs)

  + cold start elimination
  → Flex always-ready: ~$21/mo
  → Premium: included (always-on)

  + API Management
  → APIM Basic: ~$147/mo
  → OR APIM Standard v2: ~$700/mo

  + WAF protection
  → Application Gateway WAF_v2: ~$333/mo

  Flex path:
  = ~$530/mo floor (Flex + always-ready + PEs + APIM Basic + WAF)
  = ~$1,083/mo ceiling (Flex + PEs + APIM Standard v2 + WAF)

  Premium path (forced by constraints):
  = ~$656/mo floor (EP1 + PEs + APIM Basic + WAF)
  = ~$1,209/mo ceiling (EP1 + PEs + APIM Standard v2 + WAF)

Every one of these requirements is reasonable on its own. Your security team isn't wrong to ask for VNet integration. Private endpoints are a real protection. APIM and WAF exist because APIs need them.

The function plan itself is the smallest factor. On Flex, your compute cost at idle is $0 to $50/month. On Premium, it's $146 to $176. Either way, APIM and WAF add $480 to $1,033 on top. Those two services dominate the bill regardless of which Functions plan you choose.

Build and Deploy Friction

The cost story from the plan escalation section is the monthly bill. The deployment story is the engineering time you spend before your code even runs.

You cannot convert a function app from one plan to another in place. Moving from Consumption to Flex Consumption, or from Premium to Flex, means creating a new function app, redeploying your code, and deleting the old one. There is no az functionapp update --sku FC1. Microsoft's own migration guide recommends running both apps in parallel during a transition period, then cutting over. For production workloads, that's a blue-green deployment you didn't plan for.

The app settings cleanup

Flex Consumption deprecates roughly 20 app settings and site properties that other plans rely on. If you copy your existing configuration to a new Flex app without cleaning it up, the deployment fails or the app behaves unpredictably.

These settings must be removed:

# Deployment (handled by functionAppConfig.deployment.storage on Flex)
WEBSITE_RUN_FROM_PACKAGE

# Azure Files (Flex has no Azure Files dependency)
WEBSITE_CONTENTAZUREFILECONNECTIONSTRING
WEBSITE_CONTENTSHARE
WEBSITE_SKIP_CONTENTSHARE_VALIDATION

# Networking (inherited from the integrated VNet on Flex)
WEBSITE_CONTENTOVERVNET
WEBSITE_VNET_ROUTE_ALL
WEBSITE_DNS_SERVER

# Runtime (managed via functionAppConfig.runtime on Flex)
FUNCTIONS_EXTENSION_VERSION
FUNCTIONS_WORKER_RUNTIME

# Scaling (renamed in functionAppConfig.scaleAndConcurrency)
WEBSITE_MAX_DYNAMIC_APPLICATION_SCALE_OUT

The most dangerous one is WEBSITE_RUN_FROM_PACKAGE. On Consumption and Premium, this setting controls how your code gets deployed. On Flex, it must not exist. Flex uses functionAppConfig.deployment.storage to point at a blob container instead of Azure Files. If WEBSITE_RUN_FROM_PACKAGE is still present, the deployment silently uses the wrong mechanism.

Site properties change too. alwaysOn must be false on Flex (it's invalid), but true on Premium and Dedicated. functionsRuntimeScaleMonitoringEnabled is unnecessary on Flex because scale monitoring is built in, but forgetting to remove it won't break anything. ARM template properties like linuxFxVersion, containerSize, and isReserved are all replaced by the functionAppConfig section.

Infrastructure as Code breaks across plans

Your Terraform and Bicep templates don't just need new property values. They need different resources entirely.

In Terraform, azurerm_linux_function_app does not work with the Flex Consumption SKU. Attempting to provision it with an FC1 service plan fails. You need azurerm_function_app_flex_consumption, a separate resource introduced in AzureRM provider v4.21.0:

# Consumption / Premium: this resource
resource "azurerm_linux_function_app" "func" {
  service_plan_id = azurerm_service_plan.plan.id
  # ...
}

# Flex Consumption: different resource, different schema
resource "azurerm_function_app_flex_consumption" "func" {
  service_plan_id = azurerm_service_plan.plan.id

  site_config {}

  storage_container_type    = "blobContainer"
  storage_container_endpoint = "${azurerm_storage_account.sa.primary_blob_endpoint}${azurerm_storage_container.deploy.name}"
  # ...
}

The Flex resource requires a blob storage container for deployments (no Azure Files), supports maximum_instance_count and instance_memory_mb properties that don't exist on the standard resource, and has its own quirks. As of early 2026, you still need to set AzureWebJobsStorage to an empty string as a workaround when using managed identity authentication, then use AzureWebJobsStorage__accountName for the actual connection.

In Bicep, the SKU values map to different tiers:

Plan	SKU Name	SKU Tier
Consumption	`Y1`	`Dynamic`
Flex Consumption	`FC1`	`FlexConsumption`
Premium	`EP1`/`EP2`/`EP3`	`ElasticPremium`

The FC1 plan also requires reserved: true and a functionAppConfig section that replaces most of the properties you'd normally set as app settings. That's a structural rewrite of your deployment template, not a property change.

CI/CD pipeline adjustments

GitHub Actions requires the sku parameter in azure/functions-action when deploying to Flex Consumption with a publish profile:

- uses: Azure/functions-action@v1
  with:
    app-name: ${{ env.FUNCTION_APP_NAME }}
    package: ${{ env.PACKAGE_PATH }}
    publish-profile: ${{ secrets.PUBLISH_PROFILE }}
    sku: 'flexconsumption'
    remote-build: 'true'

Without sku: 'flexconsumption', the action deploys using the standard Consumption mechanism, which fails silently or produces a broken deployment. With OIDC or service principal authentication, the action can auto-detect the SKU, but publish profile deployments need it explicitly.

The scm-do-build-during-deployment and enable-oryx-build flags that you might have in your existing workflow are also wrong for Flex. Flex always performs an Oryx build during remote deployment. Setting those flags manually can interfere with the process.

Private endpoints break GitHub-hosted runners

If your function app runs on Premium with private endpoints enabled, the SCM/Kudu site is not publicly reachable. GitHub-hosted runners cannot connect to it. Your deployment fails with Failed to fetch Kudu App Settings (CODE: 404) or a 401, and the error message gives you almost no indication that networking is the problem.

Your options:

Self-hosted runner inside the VNet: works, but now you're maintaining a VM ($50-100/month) to deploy a "serverless" function
GitHub-hosted runners with Azure private networking: GitHub can inject a runner NIC directly into your VNet subnet, giving hosted runners private access without self-hosted infrastructure. Requires a GitHub Team or Enterprise Cloud plan and larger runners (2-64 vCPU, per-minute billing). Supported in 25 Azure regions as of early 2026, but notably not West Europe.
Deploy via ARM using a service principal: bypasses SCM entirely, pushes configuration through the Azure Resource Manager API
Stage to blob storage: upload your package to a storage account the function app can reach, then trigger deployment from there

On Premium, you also need WEBSITE_SKIP_CONTENTSHARE_VALIDATION=1 in your ARM or Bicep templates when the backing storage account has a firewall or private endpoints. Without it, the ARM deployment fails during content share validation because the deployment engine can't reach the storage account through the private endpoint.

The compound effect

Any one of these issues is a half-day fix. The compound effect is what costs real engineering time: you change plans, which changes your Terraform resources, which changes your app settings, which changes your GitHub Actions workflow, which breaks because of private endpoint networking. Each layer has its own failure mode, its own error messages, and its own documentation scattered across different Microsoft Learn pages.

The real cost of plan migration shows up in the sprint consumed by infrastructure work, not in the Azure bill.

When Serverless Stops Making Sense

At some point, the friction outweighs the abstraction. If you're paying $530/month or more, fighting plan migrations in Terraform, and managing deployment workarounds because private endpoints interfere with your CI pipeline, you should be asking: is the Functions hosting model still earning its keep?

Signs it's time to look elsewhere:

Your total infrastructure cost exceeds what the "serverless" label saves you in operational effort
You're spending more time working around platform constraints than building features
Your build and deploy pipeline is already as complex as it would be with containers
Your team needs operational control (sidecars, traffic splitting, custom health probes) that Functions doesn't expose

The two alternatives worth evaluating are Azure Container Apps and App Service. They solve different problems.

Azure Container Apps: the container-native path

Azure Container Apps (ACA) can host the Functions runtime directly. The v2 model, which Microsoft recommends for all new deployments, creates a single Microsoft.App resource with kind=functionapp. No hidden proxy resources, no dual-resource management. Your function app is a container app with Functions triggers and bindings wired in.

The resource definition looks like a normal container app deployment:

az containerapp create \
  --name my-func-app \
  --resource-group rg-prod \
  --environment my-aca-env \
  --image myregistry.azurecr.io/my-func:latest \
  --kind functionapp \
  --min-replicas 0 \
  --max-replicas 10

KEDA (Kubernetes-based Event Driven Autoscaling) handles scaling. The Functions runtime automatically configures KEDA scale rules based on your triggers. You don't write KEDA definitions yourself; the platform infers them from your bindings. HTTP, Service Bus, Event Hubs, Queue Storage, and other triggers all map to KEDA scalers behind the scenes, and your app can scale to zero when idle.

What you gain over Premium Functions:

Cost: a single replica at 0.25 vCPU / 512 MB idles at roughly ~$10/month on the Consumption workload profile. Compare that to Premium EP1 at ~$146/month. With scale-to-zero, idle cost drops to $0.
Sidecar containers: run log forwarders, auth proxies, or Dapr sidecars alongside your function app in the same pod
Dapr integration: pub/sub, state management, and service invocation without managing the infrastructure
Traffic splitting via revisions: route a percentage of traffic to a new version before promoting it, something Functions deployment slots can't do with the same granularity
GPU support: if you're running inference workloads alongside event-driven functions, ACA supports GPU-backed workload profiles

What you give up:

Containerization is mandatory. There is no code-only deployment path. You build a Docker image, push it to a registry, and deploy from there. If your team has no container experience, this is a real adoption cost.
No built-in continuous deployment from the Functions tooling. You wire up GitHub Actions or Azure Pipelines yourself.
Inbound Private Endpoints through the Functions networking layer are not available. The Functions networking features table on Microsoft's docs shows a blank cell for "Inbound Private Endpoints" under the Container Apps column. ACA itself supports private endpoints at the environment level (workload profiles environments only), but the Functions-specific private endpoint feature does not carry over. If your compliance requirements specifically mandate Functions inbound private endpoints, Flex Consumption or Premium are your options.

The environment-level private endpoint on ACA carries additional charges through the Dedicated Plan Management fee. Budget roughly $67-70/month for this capability, which applies at the environment level regardless of how many apps you run inside it.

App Service: the predictable option

App Service doesn't get much attention in the serverless conversation, but it's worth considering if your workload has predictable traffic and you've already left the scale-to-zero model behind. On Premium EP1, you're paying ~$146/month for a single function app that never scales to zero anyway. An App Service P1v3 plan gives you 2 vCPUs and 8 GB of memory. It supports multiple apps on the same plan, full deployment slots (up to 5 on Standard, 20 on Premium), and no cold starts. The pricing is comparable, and you get operational features that Functions on Premium doesn't match.

App Service won't give you KEDA-based event scaling or scale-to-zero. It's a fixed-compute model. But if you're already paying for always-on compute through Premium Functions, the question is whether the Functions event-driven abstractions justify the constraints that come with them.

Picking the right exit

The choice depends on what pushed you away from Functions in the first place:

If your main frustration is cost, Container Apps on the Consumption workload profile gives you scale-to-zero with VNet support at a fraction of Premium pricing. You keep the Functions programming model, triggers, and bindings.

If your frustration is operational control, Container Apps gives you sidecars, revisions, and a container runtime you can customize. The trade-off is containerization overhead and the requirement to build and manage container images.

Teams frustrated by complexity for a steady workload often find that App Service is the right fit. It strips away the serverless machinery and gives you a predictable compute environment with mature deployment tooling.

None of these are a universal upgrade. Each one trades a Functions limitation for a different set of constraints. The point is to make that trade consciously, not to discover it after migration.

Making an Honest Choice

Three plans, three different products.

Consumption is genuine serverless. Your code runs, you pay for execution time, it scales to zero when idle. If your workload is public-facing, doesn't need VNet access, and won't face a security review that mandates private networking, Consumption is the right plan. It does exactly what the marketing says. The catch: Linux Consumption enters restricted feature mode in September 2025, with full retirement in September 2028. New workloads shouldn't start here.

Flex Consumption is serverless with enterprise networking. It went GA in November 2024 and it's the plan Microsoft recommends for new dynamic-scale workloads in 2026. You get VNet integration, inbound private endpoints, scale-to-zero, and no Azure Files dependency. The constraints are real (Linux only, one app per plan, no deployment slots, 30-second init timeout), but for teams that can work within them, Flex keeps the serverless economics intact while passing a security review.

Premium is managed compute with event-driven scaling. It is not serverless. You're paying for always-on instances whether traffic arrives or not. Premium exists because some requirements (Windows, deployment slots, in-process .NET, multiple apps per plan) have no other home. If you're on Premium, own that decision. Budget for it as compute, not as serverless with extra features.

The distinction matters most at the moment you least want to think about it: during the security review, when someone asks why your function app can't reach a private endpoint. Know which plan you're actually buying before that conversation starts. Migrating between plans means deleting and recreating the function app, updating Terraform resources, and rewriting deployment pipelines. It's not a configuration change. It's a project.

Has a security review pushed you from Consumption to Premium, or did you start on Premium from day one?

Azure Functions Observability: From Blind Spots to Production Clarity

Martin Oehlert — Fri, 03 Apr 2026 06:25:08 +0000

Your function works locally, passes all tests, and deploys without errors. But how do you know it's healthy at 2am when a queue-triggered function silently drops messages? With a traditional web app on a VM, you'd SSH in, check logs, inspect process health. Serverless strips all of that away.

The observability gap in serverless is real, and it's structural. Your function runs inside an ephemeral container that spins up on demand, processes an event, and disappears. There's no persistent server to monitor, no process to attach a debugger to, no /var/log to tail. When your function app scales to zero between invocations, even continuous metric collection breaks down: there is literally nothing running to emit telemetry.

And when it scales from zero to fifty concurrent instances under load, correlating a single failed request across that distributed execution becomes a different problem entirely. Traditional APM tools assume long-lived processes with stable identities. Serverless functions violate every one of those assumptions.

Application Insights fills that gap. When connected to your function app (via a connection string, not the deprecated instrumentation key), it automatically captures request telemetry for every function execution, tracks dependencies like HTTP calls and database queries, collects host-level performance counters, and aggregates invocation metrics you can query from the portal or through code.

On top of that, it gives you structured log queries with KQL (Kusto Query Language), an application map that visualizes how your function calls downstream services, distributed tracing that follows a single request across multiple functions and dependencies, and alerting rules that can page you before your users notice something is wrong.

The examples below use the classic Application Insights SDK with the isolated worker model, which is what most production .NET function apps run today. The companion repository at azure-functions-samples has working examples of both the classic SDK (HttpTriggerDemo) and OpenTelemetry (EventHubDemo).

Setting Up Application Insights

Creating the Resource

You can create an Application Insights resource through the Azure Portal (search "Application Insights" and click Create) or provision it with Bicep alongside your function app:

resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
  name: 'appi-orders-prod'
  location: location
  kind: 'web'
  properties: {
    Application_Type: 'web'
    WorkspaceResourceId: logAnalyticsWorkspace.id
  }
}

The resource gives you a connection string, which looks like InstrumentationKey=<guid>;IngestionEndpoint=https://region.in.applicationinsights.azure.com/. Use this, not the instrumentation key alone. Microsoft deprecated standalone instrumentation key ingestion in March 2025, and connection strings are required for sovereign clouds, regional endpoints, and Entra ID-authenticated ingestion. Store the value in your function app's APPLICATIONINSIGHTS_CONNECTION_STRING application setting, and Azure picks it up automatically.

NuGet Packages

The isolated worker model needs two packages:

dotnet add package Microsoft.ApplicationInsights.WorkerService --version 2.22.0
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights --version 2.0.0

Pin Microsoft.ApplicationInsights.WorkerService to 2.22.0. Version 3.0.0 migrated to OpenTelemetry internally and broke the ITelemetryInitializer interface that Microsoft.Azure.Functions.Worker.ApplicationInsights depends on. The result is a TypeLoadException at startup:

System.TypeLoadException: Could not load type
'Microsoft.ApplicationInsights.Extensibility.ITelemetryInitializer'
from assembly 'Microsoft.ApplicationInsights, Version=3.0.0.1'

This affects every .NET version (not just .NET 10). Until the Functions worker package ships a compatible update, stay on 2.22.0. Add a comment in your .csproj so the next person who runs dotnet outdated doesn't blindly upgrade:

<!-- Do NOT upgrade to 3.x: breaks Functions worker. See github.com/Azure/azure-functions-dotnet-worker/issues/3322 -->
<PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
<PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.0.0" />
<!-- Check https://github.com/Azure/azure-functions-dotnet-worker/issues/3322 before upgrading either package -->

The second package, Microsoft.Azure.Functions.Worker.ApplicationInsights, is what connects your dependency telemetry (HTTP calls, SQL queries, queue operations) back to the parent function invocation. Without it, correlation breaks.

Program.cs Configuration

Two method calls handle the setup:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Build().Run();

AddApplicationInsightsTelemetryWorkerService() registers the Application Insights SDK for worker-style apps (background services, Functions). ConfigureFunctionsApplicationInsights() hooks into the Functions runtime's activity pipeline so that incoming triggers and outbound calls produce the right request and dependency telemetry.

See this in context in the HttpTriggerDemo Program.cs.

One catch: the SDK registers a default logging filter that suppresses everything below Warning. If you leave it in place, your ILogger.LogInformation() calls never reach Application Insights. Remove it explicitly:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
{
    LoggerFilterRule? defaultRule = options.Rules.FirstOrDefault(
        rule => rule.ProviderName ==
            "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

    if (defaultRule is not null)
    {
        options.Rules.Remove(defaultRule);
    }
});

builder.Build().Run();

Alternatively, manage log levels through appsettings.json (loaded automatically by FunctionsApplication.CreateBuilder):

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

What Gets Auto-Collected vs. What You Add Manually

Once that's in place, the SDK and the Functions runtime collect telemetry automatically, with no extra code:

Logging Best Practices

Structured Logging with ILogger

Structured logging writes log entries as key-value pairs instead of flat strings. In Application Insights, those keys become columns in the customDimensions property of the traces table, which means you can filter and aggregate by them in KQL without parsing text.

The ILogger API supports this through message templates: named placeholders wrapped in curly braces, filled by positional arguments.

public class ProcessOrderFunction(ILogger<ProcessOrderFunction> logger)
{
    [Function(nameof(ProcessOrderFunction))]
    public async Task Run(
        [QueueTrigger("orders")] OrderMessage message)
    {
        logger.LogInformation(
            "Order received: {OrderId} from customer {CustomerId}, total {OrderTotal}",
            message.OrderId,
            message.CustomerId,
            message.Total);

        var stopwatch = Stopwatch.StartNew();
        await ProcessAsync(message);
        stopwatch.Stop();

        logger.LogInformation(
            "Order {OrderId} processed successfully in {ElapsedMs}ms",
            message.OrderId,
            stopwatch.ElapsedMilliseconds);
    }
}

Two things to watch here. First, use PascalCase for placeholder names ({OrderId}, not {orderId} or {order_id}). Application Insights stores these as customDimensions keys, and PascalCase matches the convention for the rest of the telemetry schema. Second, never use string interpolation ($"Order {orderId}") in log calls. Interpolated strings defeat structured logging entirely: the provider receives a pre-formatted string with no queryable fields, and the arguments are evaluated even when the log level is disabled.

In the Application Insights traces table, a query like this pulls all logs for a specific order:

traces
| where customDimensions.OrderId == "ORD-20260330-1847"
| project timestamp, message, customDimensions.CustomerId, customDimensions.ElapsedMs
| order by timestamp asc

High-Performance Logging with Source Generators

For functions processing thousands of messages per second (high-throughput queue or Event Hub triggers), the standard LogInformation extension methods have measurable overhead: they box value-type arguments, allocate a params object[] on every call, and parse the message template at runtime.

The [LoggerMessage] source generator eliminates all three costs by generating strongly typed methods at compile time:

public static partial class OrderLogs
{
    [LoggerMessage(
        EventId = 1001,
        Level = LogLevel.Information,
        Message = "Order {OrderId} received from {CustomerId}, total {OrderTotal}")]
    public static partial void OrderReceived(
        ILogger logger, string orderId, string customerId, decimal orderTotal);

    [LoggerMessage(
        EventId = 1002,
        Level = LogLevel.Warning,
        Message = "Order {OrderId} retry attempt {RetryCount}")]
    public static partial void OrderRetrying(
        ILogger logger, string orderId, int retryCount);
}

Call these directly: OrderLogs.OrderReceived(logger, message.OrderId, message.CustomerId, message.Total). The generated code includes a log-level check before evaluating any arguments, so you pay zero cost when Information-level logging is disabled in production. Use this pattern on hot paths; for functions running a few times per minute, the standard extension methods are fine. The companion repo has source generator examples in both HttpTriggerDemo/Logging/OrderLogs.cs and EventHubDemo/Logging/SensorLogs.cs.

Correlation with BeginScope

Individual log lines tell you what happened; BeginScope ties related entries into a single operation. When you wrap your function body in a scope, every log entry inside it automatically inherits the scope's properties as customDimensions in Application Insights.

The critical detail: you must pass a Dictionary<string, object> to BeginScope for the keys to appear as individual customDimensions columns. A plain string or a message template with arguments produces a single formatted string in the scope, which is much harder to query.

[Function(nameof(ProcessOrderFunction))]
public async Task Run(
    [QueueTrigger("orders")] OrderMessage message)
{
    using var scope = logger.BeginScope(new Dictionary<string, object>
    {
        ["OrderId"] = message.OrderId,
        ["CustomerId"] = message.CustomerId,
        ["TenantId"] = message.TenantId
    });

    logger.LogInformation("Validating order");
    await ValidateAsync(message);

    logger.LogInformation("Charging payment");
    await ChargePaymentAsync(message);

    logger.LogInformation("Order complete");
}

Every log line inside that using block now carries OrderId, CustomerId, and TenantId in its customDimensions, even the ones from ValidateAsync and ChargePaymentAsync (assuming they use the same ILogger instance). This is how you trace a complete business operation across multiple internal methods without threading correlation IDs through every method signature.

Log Levels for Production

The host.json logLevel section controls which categories reach Application Insights. Two categories are easy to misconfigure, and getting them wrong silently breaks your monitoring dashboards.

{
  "logging": {
    "logLevel": {
      "default": "Warning",
      "Function": "Information",
      "Host.Results": "Information",
      "Host.Aggregator": "Trace"
    }
  }
}

Host.Results feeds the requests table. If you raise this above Information, successful function executions stop appearing in the Application Insights Performance and Failures blades, and the Function Monitor tab in the portal goes blank. You lose your primary visibility into whether functions are running at all.

Host.Aggregator feeds the customMetrics table with aggregated counts and durations. Set it to Trace so the runtime writes every batch. If you raise this to Warning or higher, the function overview dashboard in the portal loses its success rate and duration charts.

The default: Warning baseline keeps noise low for framework categories (Microsoft.*, Worker, System.*) while Function: Information ensures your own function logs reach Application Insights.

When you need to change log levels without redeploying, override any host.json value through app settings. The pattern replaces dots with double underscores:

AzureFunctionsJobHost__logging__logLevel__Function.ProcessOrder = Debug

This takes effect on the next function host restart (which happens automatically when you update an app setting) and lets you temporarily increase verbosity for a single function without touching host.json.

Sampling Configuration

Application Insights enables adaptive sampling by default, targeting 20 telemetry items per second per host. At low volume, you won't notice. At scale, sampling can silently discard traces, dependencies, and custom events before they reach your workspace.

The recommended production configuration excludes Request and Exception from sampling, so you never lose function execution records or error details:

{
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 20,
        "excludedTypes": "Request;Exception"
      }
    }
  }
}

To check whether sampling is actively dropping data, run this KQL query. Any row where TelemetrySavedPercentage is below 100 means that telemetry type is being sampled:

union traces, dependencies, requests
| where timestamp > ago(1d)
| summarize
    TelemetrySavedPercentage = round(100.0 / avg(itemCount), 1),
    TelemetryDroppedPercentage = round(100.0 - 100.0 / avg(itemCount), 1)
    by bin(timestamp, 1h), itemType
| where TelemetrySavedPercentage < 100
| order by timestamp desc

The itemCount field on each telemetry item tells you how many similar items it represents. An itemCount of 5 means Application Insights kept one item and estimated it represents five. If your traces show 30% dropped, either raise maxTelemetryItemsPerSecond or add Trace to excludedTypes for the categories that matter most to your debugging workflow. Watch your ingestion costs, though: excluding too many types from sampling at high volume can push you past your daily data cap quickly.

Reading Traces and Metrics

Once telemetry is flowing into Application Insights, you need to know where to look and what to ask. The portal gives you three entry points: Transaction Search for hunting specific executions, Log queries (KQL) for anything that requires aggregation or correlation, and the Application Map for a visual snapshot of your function app's dependencies.

Transaction Search

Transaction Search is the fastest way to find what happened to a specific function execution. Open it from the left nav in your Application Insights resource, or use the shortcut from the Investigate section of the overview blade.

The filters that matter most for Azure Functions:

Operation name: the function name as registered in the runtime (e.g., ProcessOrderFunction). Filter here when you want all executions of a specific function in a time window.
Result code: for HTTP triggers, this is the HTTP status code (200, 500, etc.). For non-HTTP triggers (queue, timer, blob), 0 means success and 1 means failure. Combine with operation name to pull only failed runs.
Time range: narrow this first, before adding other filters. Application Insights searches can time out on broad time ranges at high volume.

Click any result to open the End-to-end transaction view. This is where distributed tracing pays off: you'll see the full execution timeline as a Gantt chart, with your function's request at the top and every outbound dependency (HTTP calls to payment APIs, SQL queries, Service Bus operations) shown as child spans with their durations. If a queue-triggered ProcessOrderFunction call failed at 2am, this view tells you whether the failure was in your code, in a downstream HTTP call, or in a database query.

One limitation: Transaction Search shows individual telemetry items, not aggregated data. If you want to know "how many orders failed between 1am and 3am and which customer IDs were affected", you need KQL.

KQL Essentials for Azure Functions

All four tables you'll use most (requests, dependencies, traces, exceptions) share an operation_Id column. That ID is the distributed trace ID that ties every log line, dependency call, and exception back to the single function invocation that produced them.

Finding slow executions

The requests table records every function invocation. duration is in milliseconds.

requests
| where timestamp > ago(24h)
| where name == "ProcessOrderFunction"
| where duration > 5000
| project timestamp, id, duration, resultCode, operation_Id
| order by duration desc

This gives you the slowest ProcessOrderFunction executions in the last 24 hours. Swap > 5000 for whatever your SLA threshold is. The operation_Id in each row is your entry point into the full trace for that execution.

Tracing a single request end-to-end

You have an operation_Id from a failed execution (from Transaction Search, from an alert, or from a support ticket). This query reconstructs everything that happened:

let traceId = "abc123def456";
union requests, dependencies, traces, exceptions
| where operation_Id == traceId
| project timestamp, itemType, name, message, duration, success, resultCode, customDimensions
| order by timestamp asc

The union across all four tables is deliberate. A single function execution produces rows in multiple tables: a requests row for the invocation itself, dependencies rows for every outbound call, traces rows for your ILogger calls, and an exceptions row if something threw. The itemType column tells you which table each row came from.

If you set up BeginScope with OrderId and CustomerId as described in the logging section, those values appear in customDimensions on every trace row. You can also work backwards from a business ID when you don't have an operation_Id:

traces
| where timestamp > ago(24h)
| where customDimensions.OrderId == "ORD-20260330-1847"
| project operation_Id
| distinct operation_Id

Take that operation_Id and feed it into the union query above.

Counting failures by function name over time

requests
| where timestamp > ago(7d)
| where success == false
| summarize FailureCount = count() by bin(timestamp, 1h), name
| order by timestamp desc, FailureCount desc

This surfaces which functions fail most, and whether failures cluster at specific times (a sign of a dependency being unhealthy during a maintenance window, or a batch job hitting a resource limit).

Finding dependency bottlenecks

Your function may be fast; a downstream service may not be.

dependencies
| where timestamp > ago(24h)
| where cloud_RoleName == "your-function-app-name"
| summarize
    CallCount = count(),
    P50 = percentile(duration, 50),
    P95 = percentile(duration, 95),
    P99 = percentile(duration, 99),
    FailureRate = round(100.0 * countif(success == false) / count(), 1)
    by target, type
| order by P95 desc

Replace "your-function-app-name" with the value in your function app's Application Insights configuration (it defaults to the function app name). The target column shows the external endpoint or database, and type shows the dependency kind (HTTP, SQL, Azure Service Bus, etc.). A high P95 with a low FailureRate means the dependency is slow but not failing outright: the kind of problem that shows up as user-visible latency before it shows up as errors.

One gotcha with KQL in the portal: queries run against a Log Analytics workspace, and there's a default query scope. If you open KQL from the Application Insights blade, you're automatically scoped to that resource's workspace. If you open it from a general Log Analytics workspace, you need to add | where cloud_RoleName == "your-function-app-name" to every query, or you'll get results mixed across all resources in the workspace.

Application Map

The Application Map (left nav, under Investigate) renders your function app as a node and every dependency it calls as connected nodes. Each connection shows call volume, average duration, and failure rate. Nodes turn yellow when failure rates exceed roughly 20-30% and red above 50% (the thresholds aren't configurable).

For a ProcessOrderFunction that calls a payment API and writes to SQL, you'd see three nodes: your function app in the centre, the payment API to one side, and the SQL database to the other. The lines between them show call counts and P95 latency. If the payment API node is yellow, that's your first place to look during an incident.

The map is useful for a quick health check and for onboarding new team members, but it has limits. It aggregates across all functions in the app, so if you have ten functions and one is hammering a slow dependency, the map shows the aggregate. It also doesn't distinguish between functions calling the same dependency: if both ProcessOrderFunction and RefundOrderFunction call the same SQL database, the database shows one aggregated node. For function-level dependency analysis, go back to the KQL query above.

Alerts

Alert rules in Application Insights let you define a condition and trigger an action group (email, Teams webhook, PagerDuty, etc.) when the condition is met. You configure them under the Alerts section of your Application Insights resource.

To create a failure rate alert for ProcessOrderFunction:

Select Create > Alert rule.
Set the signal to Custom log search.

Use this KQL as the condition:

requests
| where name == "ProcessOrderFunction"
| where timestamp > ago(5m)
| summarize
    Total = count(),
    Failed = countif(success == false)
| extend FailureRate = round(100.0 * Failed / Total, 1)
| where FailureRate > 5

Set evaluation frequency to every 1 minute, and the lookback window to 5 minutes.
Configure the threshold: alert when the query returns any rows (meaning FailureRate > 5 for that window).

Action groups are the notification mechanism. One action group can send email, post to a Teams incoming webhook, and call an Azure Automation runbook simultaneously. Define your on-call action group once, then reuse it across all alert rules.

A few practical notes on alert tuning:

Start with a 5-minute window and a 5% threshold, then tighten after you've seen a few weeks of baseline data. Alerting on 1-minute windows at 1% failure rate on a low-volume function produces a lot of noise for transient errors.
The requests table has a 1-2 minute ingestion delay under normal conditions and up to 5 minutes during ingestion spikes. A 5-minute lookback window accounts for this. A 1-minute window can miss failures entirely if ingestion is delayed.
For queue-triggered functions, complement failure rate alerts with a queue depth alert on the source queue (configured through Azure Monitor metrics, not Application Insights). A growing queue combined with low invocation count means your function is failing at startup, before it even executes: a scenario that produces no requests rows and won't trigger a failure rate alert.

Common Issues and Fixes

"My logs aren't showing up in Application Insights"

It comes down to one of four things, and you can rule them out in order.

Check the connection string first. Open your function app in the portal, go to Configuration, and confirm APPLICATIONINSIGHTS_CONNECTION_STRING is set and points to the right resource. If it's missing or set to an instrumentation key only (the InstrumentationKey=<guid> format without an IngestionEndpoint), nothing reaches Application Insights at all.

Check the worker log level config. As covered in the two-pipeline gotcha above: host.json controls the host process, but your Program.cs or appsettings.json controls the worker. If you haven't explicitly configured the worker's ApplicationInsights log level, the SDK default applies: Warning only. Add this to your appsettings.json:

{
  "Logging": {
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Or remove the default filter rule entirely in Program.cs, as shown in the setup section.

Check sampling. If requests appear but traces for specific functions don't, sampling may be discarding them. Run the KQL query from the sampling section to see which telemetry types are being dropped. Add Trace to excludedTypes in host.json if you need full trace fidelity for a critical function.

Check the Function log level in host.json. If Function is set to Warning or higher, LogInformation calls from your function code never leave the host. Set it to Information to restore them.

"Dependencies are missing from the Application Map"

When your Application Map shows your function app as an isolated node with no outbound edges, check for a missing ConfigureFunctionsApplicationInsights() call in Program.cs.

AddApplicationInsightsTelemetryWorkerService() registers the SDK. ConfigureFunctionsApplicationInsights() is what connects the Functions runtime's ActivitySource to that SDK so outbound HTTP, SQL, and Azure SDK calls produce dependency telemetry with the correct operation IDs. Without it, dependencies are either not tracked at all or tracked with broken correlation (they appear in the dependencies table but don't link back to the parent request).

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights(); // Required for dependency tracking

If both calls are present and you're still missing HTTP dependencies: check how HttpClient is registered. The Application Insights SDK instruments HttpClient via IHttpClientFactory. If you're creating HttpClient instances with new HttpClient() directly instead of injecting an IHttpClientFactory-managed instance, those calls bypass the instrumentation entirely.

// Not tracked
private readonly HttpClient _client = new HttpClient();

// Tracked (inject IHttpClientFactory via primary constructor)
public class MyFunction(IHttpClientFactory httpClientFactory)
{
    private readonly HttpClient _client = httpClientFactory.CreateClient();
}

builder.Services.AddHttpClient();

"I see duplicate telemetry for every request"

In the isolated worker model, both the host process and the worker process can emit telemetry for the same function invocation. When both are sending to the same Application Insights resource, you get duplicate requests entries, inflated counts, and misleading failure rates.

This is controlled by the telemetryMode setting at the root level of host.json (not inside logging). The default is default, which allows both sides to emit. Setting it to OpenTelemetry resolves the duplication, but note that when you do, the logging.applicationInsights section of host.json no longer applies:

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry"
}

Alternatively, suppress host-side request telemetry while keeping your worker-side telemetry by raising Host.Results above Information in host.json's logLevel section. The tradeoff: this also removes successful execution records from the portal's Function Monitor tab. Use telemetryMode when you want clean deduplication without losing host-side visibility.

To confirm duplication before changing anything, run this in KQL:

requests
| where timestamp > ago(1h)
| summarize count() by operation_Id
| where count_ > 1
| order by count_ desc

Any operation_Id appearing more than once is a duplicated invocation.

"Cold start latency spikes in my metrics"

Cold starts produce latency spikes that look identical to slow execution in your metrics. Before investigating application code, confirm whether a spike is a cold start or an actual regression.

A cold start request carries a specific pattern: high latency on the first invocation from a given instance, with subsequent requests from the same instance running at normal duration. The cloud_RoleInstance dimension on each request record identifies the instance.

requests
| where timestamp > ago(24h)
| where name == "ProcessOrderFunction"
| summarize
    first_request = min(timestamp),
    p50 = percentile(duration, 50),
    p99 = percentile(duration, 99),
    request_count = count()
    by cloud_RoleInstance
| extend is_cold_start_instance = (request_count <= 3)
| order by first_request desc

Instances where request_count is 1 or 2 are almost certainly fresh scale-out instances, and their durations are not representative of your steady-state performance. Filter them out when computing your SLA metrics:

requests
| where timestamp > ago(24h)
| where name == "ProcessOrderFunction"
| join kind=inner (
    requests
    | summarize request_count = count() by cloud_RoleInstance
    | where request_count > 5
) on cloud_RoleInstance
| summarize p50 = percentile(duration, 50), p99 = percentile(duration, 99)

If the spike appears in warm instances, you have a real slowdown. If it's limited to fresh instances appearing after a scale-out event, it's cold start behavior. The two require different responses: cold starts call for pre-warming strategies or Consumption to Premium plan migration; actual slowdowns point to profiling.

"Alerts fire but I can't find the failing requests"

You set up an alert on exception count, it fires, you open the Failures blade, and the requests that caused the exceptions are gone. Sampling is discarding the evidence.

By default, Exception telemetry is sampled alongside everything else. When the SDK keeps one exception and estimates it represents five, the other four are discarded permanently. Your alert fires because the metric aggregation (which runs before sampling discards anything) saw all five. Your query returns only the one that survived.

The fix is to exclude Exception from sampling in host.json:

{
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "maxTelemetryItemsPerSecond": 20,
        "excludedTypes": "Request;Exception"
      }
    }
  }
}

Adding Request to excludedTypes ensures the parent request record is also always kept, so you can correlate the exception back to its invocation through the operation_Id. Without both, you may find the exception but not the request that caused it.

If the alert is on a custom metric rather than exceptions, check whether customMetrics is being sampled. Custom metrics emitted through TelemetryClient.GetMetric() are not affected by sampling (they're pre-aggregated in the SDK before sending). Custom events emitted with TelemetryClient.TrackEvent() are sampled, and alerts based on custom event counts can suffer the same problem. Add Event to excludedTypes if that's your signal source.

OpenTelemetry Alternative

The classic Application Insights SDK works well if your entire stack lives in Azure. But if you need to send telemetry to Grafana, Datadog, Jaeger, or any other backend alongside (or instead of) Azure Monitor, you're duplicating instrumentation code for each target. OpenTelemetry solves this at the protocol level: one set of instrumentation, one exporter interface, multiple backends.

OpenTelemetry is a CNCF project that defines a vendor-neutral API and wire format (OTLP) for traces, metrics, and logs. The same instrumentation code that sends data to Application Insights can also send to Zipkin or Collector pipelines with a config change, not a code rewrite.

The Setup

Microsoft publishes the Microsoft.Azure.Functions.Worker.OpenTelemetry package for this purpose, paired with the Azure Monitor exporter:

dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

First, enable OpenTelemetry output from the Functions host by adding "telemetryMode": "OpenTelemetry" at the root of your host.json (the same setting described in the duplicate telemetry section). Then the Program.cs registration replaces the classic SDK calls:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter(); // reads APPLICATIONINSIGHTS_CONNECTION_STRING automatically

builder.Build().Run();

UseFunctionsWorkerDefaults() hooks into the Functions runtime's ActivitySource for proper distributed trace correlation (the OpenTelemetry equivalent of ConfigureFunctionsApplicationInsights() from the classic SDK). Without it, dependency telemetry won't correlate back to the parent function invocation. See the full setup in EventHubDemo/Program.cs.

The connection string is still required; UseAzureMonitorExporter() reads APPLICATIONINSIGHTS_CONNECTION_STRING from the environment the same way the classic SDK does. If you also want to export to a second backend (requires the additional OpenTelemetry.Exporter.OpenTelemetryProtocol package), register it separately:

builder.Services
    .AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Services
    .AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddOtlpExporter(otlp =>
        {
            otlp.Endpoint = new Uri("http://localhost:4317");
        }));

UseAzureMonitorExporter() is a cross-cutting registration that configures all signals at once. Chaining signal-specific exporters like AddOtlpExporter after it in the same builder can throw a NotSupportedException. Separate AddOpenTelemetry() calls avoid the conflict.

What You Gain

W3C Trace Context is the default propagation format, which means your distributed traces correlate correctly with other OpenTelemetry-instrumented services regardless of what backend they report to. With the classic SDK you get this too, but only within the Application Insights ecosystem; outside it, the format diverges.

You also get multi-backend export: Azure Monitor for your ops team, a Grafana stack for your platform team, and a local Collector for local debugging, all from the same process. And if you ever migrate off Azure Monitor entirely, you replace one exporter registration, not every TelemetryClient call in your codebase.

What You Lose Today

The OpenTelemetry path is not at feature parity with the classic SDK for Functions specifically.

Live Metrics (the real-time stream at monitor.azure.com) does not work with the distro. It relies on a proprietary push mechanism in the classic SDK that has no OpenTelemetry equivalent yet.

Snapshot Debugger is unavailable. It's a classic SDK feature with no OTLP counterpart.

Auto-collection gaps: some dependency types that the classic SDK instruments automatically (certain Azure SDK operations, Service Bus settlement calls) may not be captured out of the box, depending on which OpenTelemetry instrumentation libraries you've added. You may need to add AddAzureClientsInstrumentation() or equivalent packages explicitly.

Documentation: the distro's documentation for Functions scenarios specifically is thin. Most samples target ASP.NET Core web apps; you'll spend time adapting them and testing whether auto-collection works for your trigger types.

When to Choose Which

Use the classic SDK if:

your entire workload runs on Azure and you have no multi-vendor requirements
you need Live Metrics or Snapshot Debugger
you want the richest out-of-the-box experience with the Application Insights portal today

Use OpenTelemetry if:

you're sending telemetry to multiple backends, or planning to
the rest of your services are already OpenTelemetry-instrumented and you need consistent trace propagation across the board
you're building something that might not always live in Azure

If you're greenfield on a purely Azure stack, the classic SDK is less configuration for the same result right now. If you're instrumenting a heterogeneous system or building for portability, OpenTelemetry's overhead is worth it; you pay once at setup and gain the flexibility when requirements change.

What's Next

This is Part 9 and the final article in the core series. Over nine weeks, this series went from "what is serverless" to querying production telemetry in KQL. If you followed along and built something, you now have a function app with HTTP and queue triggers, proper configuration with Key Vault, a CI/CD pipeline through GitHub Actions, and Application Insights wired up for structured logging, distributed tracing, and alerting. That covers the full lifecycle: build, test, deploy, monitor.

The companion repository at azure-functions-samples has working code for every article in the series. Clone it, break things, wire up your own alerts.

Next week is a bonus article outside the core series: production cost realities on the Consumption plan, and the signals that tell you it's time to move to Flex Consumption or Premium. If you've ever wondered why your monthly bill looked nothing like the pricing calculator, that one is for you.

When you first wired up monitoring on a production function app, which alert did you set up first: failure rate or latency?

Deploying to Azure: CI/CD with GitHub Actions

Martin Oehlert — Fri, 27 Mar 2026 06:36:06 +0000

Introduction: from local to production

Local tooling hides four things you have to own in production: packaging, authentication, configuration injection, and rollback. func start handles all of them silently; a CI/CD pipeline does not, and the decisions you make about each one compound quickly.

The gap is easy to miss. Your local environment reads from local.settings.json, authenticates with your personal identity, and recovers from bad deploys by letting you just restart. Azure does none of that for you. You need a packaging step, a way to authenticate from a pipeline without storing secrets, a strategy for injecting environment-specific configuration, and some mechanism for rolling back when a deploy breaks something.

This article covers two stages of that journey. First, manual deployment using the Azure CLI and the Functions Core Tools: useful for quick validation and understanding what the automated pipeline will do under the hood. Then a GitHub Actions workflow with two jobs, OIDC authentication (no stored credentials in your repository), deployment slots for zero-downtime releases, and configuration management that keeps secrets out of your pipeline definition entirely.

Manual deployment options

Before wiring up a full CI/CD pipeline, understand what actually happens when code reaches Azure. Manual deployment gives you that visibility, and it remains useful long after you've automated everything: for one-off hotfixes, for validating a packaging issue, or for deploying to a scratch environment without spinning up a workflow run.

func azure functionapp publish

The Core Tools command is the closest thing to a one-stop deploy:

func azure functionapp publish <APP_NAME>

Under the hood, it runs dotnet build --output bin/publish, creates a .zip archive (filtered by your .funcignore), uploads the archive via the Kudu ZipDeploy API (or One Deploy for Flex Consumption plans), and then syncs triggers and restarts the host. By default it also sets WEBSITE_RUN_FROM_PACKAGE=1 on the app, covered in the next subsection.

Flags you'll reach for regularly:

# Skip the local build — useful when you've already built in CI
func azure functionapp publish <APP_NAME> --no-build

# Deploy to a staging slot instead of production
func azure functionapp publish <APP_NAME> --slot staging

# Push local.settings.json values to app settings (prompts for confirmation)
func azure functionapp publish <APP_NAME> --publish-local-settings -i

# Verify what files will be included before committing to a deploy
func azure functionapp publish <APP_NAME> --list-included-files

Run --list-included-files at least once per project. If your archive includes bin/ debug artifacts, test assemblies, or secrets you meant to .funcignore, you want to catch that before it's sitting on a production host.

A minimal .funcignore for a .NET project:

*.csproj
*.sln
.git/
.vscode/
local.settings.json
test/

local.settings.json is the most important exclusion: it often contains connection strings and keys meant for local development only.

Azure CLI: two commands, two APIs

The Azure CLI gives you two distinct options, and picking the wrong one for your plan type will fail silently or throw a confusing error.

# Kudu ZipDeploy — works for Consumption, Premium, and Dedicated plans
az functionapp deployment source config-zip \
  -g <RESOURCE_GROUP> -n <APP_NAME> --src ./publish.zip

# One Deploy API — required for Flex Consumption, also valid elsewhere
az functionapp deploy \
  -g <RESOURCE_GROUP> -n <APP_NAME> --src-path ./publish.zip --type zip

The older config-zip command talks directly to Kudu and does no building; you're responsible for providing a publish-ready zip. It does not support Flex Consumption, the newer serverless plan that bypasses Kudu entirely. If you're on Flex Consumption, az functionapp deploy is the only CLI path that works. It also gives you --clean to remove files not in the archive and --async to return immediately without polling for completion.

A rule of thumb: if you're writing a deploy script that needs to work across plan types, use az functionapp deploy. If you're on a legacy plan and config-zip already exists in your runbooks, it's fine to leave it.

Run-From-Package and why it matters

When WEBSITE_RUN_FROM_PACKAGE=1 is set, Azure mounts your zip archive as a read-only filesystem at wwwroot rather than extracting files into it. This is the default behavior when you publish with Core Tools, and it has real production benefits: deployment is atomic (the old package stays mounted until the new one is ready), file-copy locking errors disappear, and cold start times improve because the runtime reads directly from the zip.

The constraints: wwwroot becomes read-only (portal-based editing no longer works), the archive has a 1 GB limit, and you should not set this value on Flex Consumption plans, which manage packages differently.

Which method to use

For anything beyond a one-off fix or an afternoon prototype, these manual commands are the foundation you'll extract into a pipeline. Knowing what each one does makes the GitHub Actions steps in the next section easier to reason about when something goes wrong.

GitHub Actions workflow setup

The pieces fit together like this:

The build job produces a single artifact. The deploy job authenticates via OIDC, pushes to a staging slot, and swaps it into production.

The complete workflow is below. Read through it first; the walkthrough after explains the decisions behind each piece.

name: Deploy Azure Functions (.NET 10)

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
          cache: true

      - run: dotnet restore --locked-mode

      - run: >
          dotnet publish src/MyFunctionApp
          --configuration Release
          --output ./output
          --runtime linux-x64
          --self-contained true

      - uses: actions/upload-artifact@v4
        with:
          name: function-app
          path: ./output
          retention-days: 3

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment: production
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: function-app
          path: ./output

      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - uses: Azure/functions-action@v1
        with:
          app-name: ${{ vars.FUNCTION_APP_NAME }}
          slot-name: staging
          package: ./output

      - name: Swap staging to production
        uses: azure/cli@v2
        with:
          inlineScript: |
            az functionapp deployment slot swap \
              --name ${{ vars.FUNCTION_APP_NAME }} \
              --resource-group ${{ vars.RESOURCE_GROUP }} \
              --slot staging \
              --target-slot production

This is the same function app from Parts 1 through 7. The complete source is in the azure-functions-samples repository. Every push to main builds it, deploys to a staging slot, and swaps to production. No secrets stored, no manual steps, and a rollback is one swap away.

If your plan doesn't support slots (Consumption with only one slot available, or Flex Consumption), remove the slot-name parameter and the swap step. The functions-action will deploy directly to production.

Why two jobs instead of one

The split between build and deploy exists for two reasons.

First, the artifact produced by build is reusable. If you add a staging environment later, the deploy job can run twice against the same artifact without rebuilding. Build once, deploy to as many environments as you need.

Second, the id-token: write permission required for OIDC authentication (covered in the next section) is scoped to the deploy job only. If you set it at the workflow level, every job gets that elevated permission. Keeping it on the deploy job limits the blast radius if something goes wrong.

The build job

actions/checkout@v4 pulls your code. actions/setup-dotnet@v4 installs the SDK, and the cache: true option tells it to cache the NuGet package cache between runs.

That cache only works if your project has a lock file. Add this to your .csproj:

<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>

Then commit the generated packages.lock.json. Without it, cache: true has nothing to hash (so every run misses the cache), and --locked-mode silently regenerates a new lock file instead of validating against a committed one. With both in place, clean builds skip the network entirely for packages that haven't changed.

The publish step is where .NET 10 requires extra care:

dotnet publish src/MyFunctionApp \
  --configuration Release \
  --output ./output \
  --runtime linux-x64 \
  --self-contained true

--self-contained true is required for .NET 10. The Azure Functions v4 host runs on .NET 8. If you publish a framework-dependent app targeting .NET 10, the host cannot find the .NET 10 runtime and the deployment fails with exit code 150 (0x96). A self-contained publish bundles the runtime with your app, so the host's .NET version becomes irrelevant.

actions/upload-artifact@v4 takes the ./output folder and makes it available to downstream jobs. The name value (function-app) is how the deploy job will refer to it.

The deploy job

needs: build means this job waits for the build to succeed before starting. environment: production ties the job to a GitHub environment, which lets you add required reviewers or protection rules before any deployment proceeds.

actions/download-artifact@v4 retrieves the artifact by the same name used during upload and places it in ./output.

azure/login@v2 handles authentication using OIDC; the specifics of how to configure this are in the next section. This step must come before functions-action, and the three secrets (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_SUBSCRIPTION_ID) must be set in your repository or environment settings.

Azure/functions-action@v1 does the actual deployment. Two parameters are required: app-name (the name of your Function App in Azure) and package (the path to your artifact). An optional slot-name parameter targets a deployment slot if you are using them.

The deployment method the action uses depends on your hosting plan. Flex Consumption plans use One Deploy; all other plans use Zip Deploy. The action picks this automatically based on your app's plan type, so you do not need to configure it explicitly.

OIDC authentication (no stored secrets)

The workflow above uses three secrets: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID. None of them are actual credentials. That's the point of OIDC.

Why not publish profiles or service principal secrets?

Publish profiles are XML files containing deployment credentials baked into the Function App. They work, but they create problems at scale: they can't be scoped to a branch or environment, they don't expire on a schedule, and if one leaks, anyone with the file can deploy to your app until you manually reset it.

Service principal secrets are better (they support expiration and RBAC scoping), but you still have a secret stored in GitHub that needs rotating every 6-24 months. Miss a rotation and your pipeline breaks silently on the next deploy.

OIDC eliminates stored credentials entirely. GitHub mints a short-lived token for each workflow run, Azure validates that token against a federated credential you configure once, and nothing secret ever sits in your repository settings.

How it works

Your workflow requests an OIDC token from GitHub's token service
The azure/login action sends that token to Microsoft Entra ID
Entra validates the token's issuer (token.actions.githubusercontent.com), audience, and subject claim (which encodes the repo, branch, and environment)
If the claims match your federated credential configuration, Entra issues an Azure access token
The access token is used for the deployment, then expires

The subject claim is what makes this granular. You can restrict a credential to only work from a specific environment (repo:your-org/your-repo:environment:production), a specific branch, or even pull requests. A token minted from a feature branch won't match a credential scoped to the production environment.

Setup steps

1. Create an Entra app registration with a service principal:

az ad app create --display-name "github-deploy-my-func-app"
az ad sp create --id <APP_ID>

2. Assign the Website Contributor role scoped to the resource group containing your Function App:

az role assignment create \
  --assignee <APP_ID> \
  --role "Website Contributor" \
  --scope /subscriptions/<SUB_ID>/resourceGroups/<RG_NAME>

Website Contributor is enough for deploying code. Contributor works too but grants more access than the pipeline needs.

3. Configure a federated identity credential:

{
  "name": "github-actions-production",
  "issuer": "https://token.actions.githubusercontent.com",
  "subject": "repo:your-org/your-repo:environment:production",
  "audiences": ["api://AzureADTokenExchange"]
}

az ad app federated-credential create \
  --id <APP_ID> \
  --parameters @credential.json

The subject field must match exactly. If your deploy job uses environment: production, the subject must end with :environment:production. If you deploy from a branch without an environment, use :ref:refs/heads/main instead.

4. Store the IDs as GitHub environment secrets:

Go to your repository Settings > Environments > production > Environment secrets, and add:

AZURE_CLIENT_ID: the Application (client) ID from your app registration
AZURE_TENANT_ID: your Entra tenant ID
AZURE_SUBSCRIPTION_ID: the subscription containing your Function App

These are identifiers, not credentials. Even if someone reads them, they can't authenticate without a valid OIDC token from your specific repository and environment.

Workflow permissions

The deploy job needs id-token: write to mint the OIDC token:

deploy:
  permissions:
    id-token: write
    contents: read

Set this on the deploy job only, not at the workflow level. The build job doesn't need token-minting permissions.

One gotcha

The Azure/functions-action supports two authentication methods: publish-profile and the azure/login action. They are mutually exclusive. If you pass a publish-profile parameter while also using azure/login, the action uses the publish profile and ignores your OIDC session. Remove the publish-profile parameter entirely when switching to OIDC.

Deployment slots and zero-downtime releases

Deploying directly to production means every release has a moment where either the old code or the new code is partially running. Deployment slots give you a staging URL to validate before any production traffic sees the new version, and an instant rollback if something goes wrong.

What each plan supports

If you're on Flex Consumption, skip to the rolling updates section below.

The blue-green pattern

Deploy to a staging slot, verify it works, then swap staging into production.

Deploy to staging: your CI/CD pipeline targets the staging slot instead of production
Validate: hit the staging URL (your-func-app-staging.azurewebsites.net) with smoke tests or manual checks
Swap: Azure switches the routing so staging serves production traffic
Rollback if needed: swap again to revert (the old production code is now in the staging slot)

The swap itself takes seconds. Your users see either the old version or the new version, never a half-deployed state.

What swaps and what stays

This trips people up. During a swap, code and most settings travel together from staging to production. But some things are pinned to the slot:

Travels with code (gets swapped): general app settings (unless marked sticky), connection strings (unless marked sticky), handler mappings, public certificates.

Stays with the slot: publishing endpoints, custom domains, TLS/SSL certificates, scale settings, IP restrictions, Always On, FUNCTIONS_EXTENSION_VERSION (sticky by default).

Sticky settings that cause problems

Two settings deserve special attention:

FUNCTIONS_EXTENSION_VERSION is sticky by default. If your staging slot runs ~4 and production also runs ~4, this is invisible. But if you ever need to change the version, the stickiness means the setting won't swap with the code. To make it travel with the swap, set WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 on all slots.

WEBSITE_CONTENTSHARE is auto-generated per slot and should never be set manually. Each slot needs its own content share to avoid file locking conflicts. If you see deployment failures mentioning "cannot access file," check whether slots are sharing this value.

Deploy-to-slot and swap in GitHub Actions

Add slot-name to the deploy step, then swap using the Azure CLI:

- uses: Azure/functions-action@v1
  with:
    app-name: 'my-func-app'
    slot-name: staging
    package: ./output

- name: Swap staging to production
  uses: azure/cli@v2
  with:
    inlineScript: |
      az functionapp deployment slot swap \
        --name my-func-app \
        --resource-group my-rg \
        --slot staging \
        --target-slot production

Swap gotchas

Watch for these:

Running functions are terminated during a swap. There is no graceful drain. If you have long-running executions, they will be killed. For timer or queue triggers, the runtime will pick up incomplete work after the swap, but HTTP requests in flight will fail.
Warm-up matters. After a swap, the new production instances need to initialize. Set WEBSITE_SWAP_WARMUP_PING_PATH to an endpoint (like a health check) that forces initialization before traffic arrives.
Keep app names under 32 characters. Longer names can cause host ID collisions between slots, leading to unexpected behavior.

Flex Consumption alternative: rolling updates

Flex Consumption doesn't support slots, but it offers rolling updates as an alternative. With siteUpdateStrategy.type set to RollingUpdate, Azure replaces instances in batches rather than all at once, giving in-progress executions a 60-minute grace period to complete.

The trade-off: there's no separate staging URL for validation, no way to split traffic between versions, and rollback means redeploying the previous version rather than an instant swap.

Environment configuration in pipelines

A deployment pipeline needs to put the right configuration in the right environment without leaking secrets into workflow files. GitHub Environments, the secrets hierarchy, and Key Vault references each handle a piece of this.

GitHub Environments

Environments are configured under your repository's Settings > Environments. Each environment can have:

Required reviewers (up to 6 people who must approve before the deploy job runs)
Wait timers (a delay before deployment proceeds, useful for change windows)
Deployment branches (restrict which branches can target this environment)

In the workflow, environment: production on a job ties it to that environment's rules. The job will pause and wait for approval if reviewers are configured.

Secrets hierarchy

GitHub secrets exist at three levels:

When the same secret name exists at multiple levels, environment wins over repository, which wins over organization. This means you can set AZURE_CLIENT_ID at the environment level with different values for development, staging, and production, each pointing to a different service principal scoped to its own resource group.

Setting app configuration during deployment

Your Function App needs configuration values beyond what's in the code. The most direct approach is the Azure CLI:

- name: Configure app settings
  uses: azure/cli@v2
  with:
    inlineScript: |
      az functionapp config appsettings set \
        --name ${{ vars.FUNCTION_APP_NAME }} \
        --resource-group ${{ vars.RESOURCE_GROUP }} \
        --settings \
          "ServiceBus__Connection=${{ secrets.SERVICEBUS_CONNECTION }}" \
          "FeatureFlags__NewCheckout=true"

Use vars (GitHub Variables) for non-sensitive configuration and secrets for anything you wouldn't put in a log file.

One warning if you manage settings through Bicep or ARM templates instead: the ARM API replaces all app settings on each deployment. If your template omits a setting that exists on the app, that setting gets deleted. The CLI's appsettings set command merges instead, which is safer for incremental updates.

Multi-environment workflow

The build-once-deploy-many pattern chains environments with approval gates:

jobs:
  build:
    runs-on: ubuntu-latest
    # ... build steps from earlier ...

  deploy-dev:
    needs: build
    environment: development
    runs-on: ubuntu-latest
    steps:
      # download artifact, azure/login, functions-action
      # (same structure, different secrets per environment)

  deploy-staging:
    needs: deploy-dev
    environment: staging
    runs-on: ubuntu-latest
    steps:
      # deploy to staging slot, run smoke tests

  deploy-production:
    needs: deploy-staging
    environment: production  # approval gate triggers here
    runs-on: ubuntu-latest
    steps:
      # swap staging to production

The same artifact flows through all three environments. The only things that change are the secrets (different AZURE_CLIENT_ID per environment, each scoped to its own resource group) and the deployment target.

Key Vault integration

This ties back to Part 6 (Configuration Done Right). Instead of passing secret values through your pipeline, store them in Key Vault and reference them in app settings:

ServiceBus__Connection=@Microsoft.KeyVault(VaultName=my-kv;SecretName=servicebus-conn)

Your pipeline sets the reference, not the secret value. The Function App's managed identity resolves the actual value at runtime using the Key Vault Secrets User role. The pipeline never sees the secret, and rotating it in Key Vault takes effect without redeployment.

If you use deployment slots, mark Key Vault references as slot settings when different environments need different secrets (e.g., staging points to a staging Key Vault, production to a production Key Vault).

What goes where

Closing

Eight articles, one function app, and a pipeline that deploys itself. If something in your own setup doesn't match what's here, the series navigation links every piece: from the first HTTP trigger through testing to this deployment workflow.

Do you deploy straight to production or use a staging slot? What made you choose one over the other?

Figuring out what actually needs a real Azure connection vs. what you can just test with a plain class… that’s where most testing headaches start. I wrote up how I handle it: unit tests, Testcontainers + Azurite, and full func start pipelines.

Martin Oehlert — Sat, 21 Mar 2026 06:16:23 +0000

Martin Oehlert

Mar 20

Testing Azure Functions: Unit, Integration, and Local

#azure #azurefunctions #serverless #dotnet

Comments

15 min read

Testing Azure Functions: Unit, Integration, and Local

Martin Oehlert — Fri, 20 Mar 2026 07:17:37 +0000

Where do you draw the line between what needs a full Azure connection and what can be tested with a plain class instantiation? The isolated worker model makes the answer concrete: the function class is just wiring. Everything testable lives in a service class that knows nothing about Azure.

Most testing pain comes from not drawing that line early enough.

The design decision that makes testing possible

Consider a function that does its own work:

public class OrderFunction(ILogger<OrderFunction> logger, SqlConnection db)
{
    [Function("CreateOrder")]
    public async Task<IActionResult> CreateOrder(
        [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "orders")] HttpRequest req,
        [FromBody] CreateOrderRequest order)
    {
        if (order.Quantity <= 0)
            return new BadRequestObjectResult("Quantity must be greater than zero");

        var orderId = "ORD-" + Guid.NewGuid().ToString("N")[..8];

        await db.ExecuteAsync(
            "INSERT INTO Orders (OrderId, ProductId, Quantity) VALUES (@OrderId, @ProductId, @Quantity)",
            new { orderId, order.ProductId, order.Quantity });

        logger.LogInformation("Created order {OrderId}", orderId);
        return new CreatedResult($"/orders/{orderId}", new { orderId, order.ProductId, order.Quantity });
    }
}

To unit test this, you need a real SqlConnection. That means a real database, which means either a running SQL Server, Testcontainers, or a brittle in-memory substitute. Every test becomes an infrastructure test, even for something as simple as verifying that a zero quantity returns 400.

The fix is to move the logic into a service class, leaving the function with nothing to do except call the service and map the result to a response:

public class OrderFunction(IOrderService orderService)
{
    [Function("CreateOrder")]
    public async Task<IActionResult> CreateOrder(
        [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "orders")] HttpRequest req,
        [FromBody] CreateOrderRequest order)
    {
        var result = await orderService.CreateOrderAsync(order);

        if (!result.IsSuccess)
            return new BadRequestObjectResult(result.Error);

        return new CreatedResult($"/orders/{result.Order!.OrderId}", result.Order);
    }
}

The function class is now three lines of routing logic. IOrderService is a plain interface with no Azure types, no infrastructure, nothing that requires a running host to instantiate.

This gives you two separate test targets. The service holds the logic and gets fast, isolated unit tests with no framework setup. The function class holds the routing and gets a thin layer of tests that verify the HTTP response shapes. Each layer can be tested on its own terms.

Unit testing the service layer

The service has one dependency worth injecting for tests: IOrderRepository. Here's the full service:

public class OrderService(ILogger<OrderService> logger, IOrderRepository repository) : IOrderService
{
    public async Task<OrderResult> CreateOrderAsync(CreateOrderRequest request)
    {
        if (request.Quantity <= 0)
            return OrderResult.Failure("Quantity must be greater than zero");

        var order = new Order(
            OrderId: "ORD-" + Guid.NewGuid().ToString("N")[..8],
            ProductId: request.ProductId,
            Quantity: request.Quantity);

        await repository.SaveAsync(order);

        logger.LogInformation("Created order {OrderId} for {ProductId}", order.OrderId, order.ProductId);

        return OrderResult.Success(order);
    }
}

To test it, you need xUnit and NSubstitute. The .csproj is minimal:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <IsTestProject>true</IsTestProject>
    <!-- Test method names use underscores by convention (MethodName_Condition_Expected) -->
    <NoWarn>$(NoWarn);CA1707</NoWarn>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" />
    <PackageReference Include="NSubstitute" />
    <PackageReference Include="xunit" />
    <PackageReference Include="xunit.runner.visualstudio">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
    </PackageReference>
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="../HttpTriggerDemo/HttpTriggerDemo.csproj" />
  </ItemGroup>
</Project>

The tests themselves need no Azure infrastructure:

public class OrderServiceTests
{
    private readonly IOrderRepository _repository = Substitute.For<IOrderRepository>();
    private readonly OrderService _service;

    public OrderServiceTests()
    {
        _service = new OrderService(NullLogger<OrderService>.Instance, _repository);
    }

    [Fact]
    public async Task CreateOrderAsync_WithValidRequest_ReturnsSuccess()
    {
        var request = new CreateOrderRequest("WIDGET-42", 3);

        var result = await _service.CreateOrderAsync(request);

        Assert.True(result.IsSuccess);
        Assert.NotNull(result.Order);
        Assert.Equal("WIDGET-42", result.Order.ProductId);
        Assert.Equal(3, result.Order.Quantity);
    }

    [Fact]
    public async Task CreateOrderAsync_WithValidRequest_SavesOrderToRepository()
    {
        var request = new CreateOrderRequest("WIDGET-42", 3);

        await _service.CreateOrderAsync(request);

        await _repository.Received(1).SaveAsync(Arg.Is<Order>(o =>
            o.ProductId == "WIDGET-42" && o.Quantity == 3));
    }

    [Theory]
    [InlineData(0)]
    [InlineData(-1)]
    [InlineData(-100)]
    public async Task CreateOrderAsync_WithInvalidQuantity_ReturnsFailure(int quantity)
    {
        var request = new CreateOrderRequest("WIDGET-42", quantity);

        var result = await _service.CreateOrderAsync(request);

        Assert.False(result.IsSuccess);
        Assert.NotNull(result.Error);
    }

    [Theory]
    [InlineData(0)]
    [InlineData(-1)]
    public async Task CreateOrderAsync_WithInvalidQuantity_DoesNotCallRepository(int quantity)
    {
        var request = new CreateOrderRequest("WIDGET-42", quantity);

        await _service.CreateOrderAsync(request);

        await _repository.DidNotReceive().SaveAsync(Arg.Any<Order>());
    }
}

NullLogger<T>.Instance is the right choice for service tests. You are testing behavior, not logging output. Using Substitute.For<ILogger<T>>() to verify that specific log messages were emitted is a fragile approach: log messages are implementation details that change often and aren't part of the service contract. Save NSubstitute for dependencies whose behavior actually matters to the test outcome, like IOrderRepository.

[Theory] + [InlineData] handles the validation branches without duplicating test body. Each InlineData value runs as a separate test in the output, so you get clear signal on exactly which inputs fail. The two [Theory] blocks above run 3 + 2 = 5 test cases from a handful of lines.

Received() and DidNotReceive() are NSubstitute's call-count assertions. The second [Fact] verifies the repository was called with the right data; the second [Theory] verifies it was never called when validation fails. Together they cover both the happy path and the guard clause.

Unit testing the function class

When you use ConfigureFunctionsWebApplication() (the ASP.NET Core integration mode), the function's HttpRequest is a standard ASP.NET Core HttpRequest. That means you can construct a DefaultHttpContext in tests and pass context.Request directly to the function method, with no Functions runtime involved:

public class OrderFunctionTests
{
    private readonly IOrderService _orderService = Substitute.For<IOrderService>();
    private readonly OrderFunction _function;

    public OrderFunctionTests()
    {
        _function = new OrderFunction(_orderService);
    }

    [Fact]
    public async Task CreateOrder_WhenServiceSucceeds_Returns201Created()
    {
        var request = new CreateOrderRequest("WIDGET-42", 3);
        var order = new Order("ORD-ABCD1234", "WIDGET-42", 3);
        _orderService.CreateOrderAsync(request).Returns(OrderResult.Success(order));

        var result = await _function.CreateOrder(new DefaultHttpContext().Request, request);

        var created = Assert.IsType<CreatedResult>(result);
        Assert.Equal("/orders/ORD-ABCD1234", created.Location);
        Assert.Equal(order, created.Value);
    }

    [Fact]
    public async Task CreateOrder_WhenServiceFails_Returns400BadRequest()
    {
        var request = new CreateOrderRequest("WIDGET-42", -1);
        _orderService.CreateOrderAsync(request)
            .Returns(OrderResult.Failure("Quantity must be greater than zero"));

        var result = await _function.CreateOrder(new DefaultHttpContext().Request, request);

        var bad = Assert.IsType<BadRequestObjectResult>(result);
        Assert.Equal("Quantity must be greater than zero", bad.Value);
    }
}

Notice what these tests do not cover: the [HttpTrigger] attribute, binding resolution, middleware, or anything the Functions host owns. That's intentional. The function's responsibility is to map a service result to an HTTP response. Two tests cover both outcome branches. Anything beyond that is integration territory.

The [HttpTrigger] and [FromBody] attributes are metadata for the runtime. They don't execute during a direct method call, so there's nothing to test or mock.

Timer triggers

Timer functions follow the same pattern. TimerInfo is a concrete class from the Functions SDK with settable properties, so you construct it directly:

public class CleanupFunctionTests
{
    private readonly CleanupFunction _function =
        new(NullLogger<CleanupFunction>.Instance);

    [Fact]
    public async Task Run_WhenOnSchedule_CompletesWithoutError()
    {
        var timer = new TimerInfo { IsPastDue = false };

        await _function.Run(timer);

        // No exception thrown = the function handled the timer correctly.
        // Timer functions have no return value — the observable outcome is
        // either successful completion or an exception.
    }

    [Fact]
    public async Task Run_WhenPastDue_StillCompletes()
    {
        var timer = new TimerInfo { IsPastDue = true };

        await _function.Run(timer);
    }
}

Timer function tests are often this minimal. The function's behavior on IsPastDue = true is to log a warning; there's no meaningful return value to assert on. What you're verifying is that the function reaches completion without throwing, and that the IsPastDue branch doesn't break anything. If your cleanup function does real work (deleting records, archiving blobs), that work lives in a service and gets tested through the service tests, not through the function.

Integration testing with Testcontainers

Unit tests get you 80% of the way. They don't verify that DI registrations are correct, that your database schema matches your queries, or that a real TableClient call actually persists what you think it does. That's two separate problems: the composition root, and the data layer.

Verifying the composition root

The first failure mode is silent: a service registration is missing, and OrderFunction's constructor throws at runtime while every unit test passes. A composition test catches this without Docker:

public class HostIntegrationTests : IAsyncLifetime
{
    private IHost _host = null!;

    public async Task InitializeAsync()
    {
        _host = new HostBuilder()
            .ConfigureFunctionsWebApplication()
            .ConfigureServices(services =>
            {
                // WorkerHostedService opens a gRPC channel to the Functions host.
                // That host doesn't exist in tests — remove it or the build hangs.
                var worker = services.FirstOrDefault(s =>
                    s.ImplementationType?.Name == "WorkerHostedService");
                if (worker is not null)
                    services.Remove(worker);
            })
            .Build();

        await _host.StartAsync();
    }

    [Fact]
    public void IOrderService_ResolvesFromDi()
    {
        var service = _host.Services.GetService<IOrderService>();
        Assert.NotNull(service);
    }

    public async Task DisposeAsync() => await _host.StopAsync();
}

WebApplicationFactory<Program> fails with Azure Functions isolated worker. The model uses gRPC for host-worker communication, and the factory hits a channel URI parsing error when no Functions host is running. The HostBuilder approach mirrors Program.cs exactly, with the gRPC listener stripped. This test doesn't call any function logic; it only verifies the container compiles.

Testing the data layer

InMemoryOrderRepository lets unit tests run fast, but it tells you nothing about whether your actual persistence works. A production implementation using Azure Table Storage looks like this:

public class TableStorageOrderRepository(TableClient tableClient) : IOrderRepository
{
    public async Task SaveAsync(Order order)
    {
        var entity = new TableEntity(order.ProductId, order.OrderId)
        {
            ["Quantity"] = order.Quantity
        };
        await tableClient.AddEntityAsync(entity);
    }
}

The integration test spins up Azurite in Docker via Testcontainers:

public class TableStorageOrderRepositoryTests : IAsyncLifetime
{
    private readonly AzuriteContainer _azurite = new AzuriteBuilder().Build();

    public async Task InitializeAsync() => await _azurite.StartAsync();

    [Fact]
    public async Task SaveAsync_WithValidOrder_PersistsToTableStorage()
    {
        var client = new TableClient(_azurite.GetConnectionString(), "orders");
        await client.CreateIfNotExistsAsync();

        var repository = new TableStorageOrderRepository(client);
        var order = new Order("ORD-TEST01", "WIDGET-42", 3);

        await repository.SaveAsync(order);

        var entity = await client.GetEntityAsync<TableEntity>(
            order.ProductId, order.OrderId);
        Assert.Equal(3, entity.Value["Quantity"]);
    }

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

Add one package to the test project:

<PackageReference Include="Testcontainers.Azurite" />

Each test run gets a fresh container. No ports to reserve, no cleanup between runs; Testcontainers handles port allocation for parallel CI execution automatically.

The same pattern covers blob and queue operations. For relational databases, Testcontainers.MsSql and Testcontainers.PostgreSql provide the same lifecycle wrapper for SQL Server and Postgres.

Local E2E testing with `func start` + Azurite

Logic tests cover OrderService. Repository tests cover TableStorageOrderRepository. Neither covers what happens when the Functions host receives an HTTP request, routes it through middleware, deserializes the body, calls the function, and returns a response.

For that, the host must be running. The approach is to start Azurite and func start together in the test fixture:

public class FunctionsE2ETests : IAsyncLifetime
{
    private readonly AzuriteContainer _azurite = new AzuriteBuilder().Build();
    private Process? _funcProcess;
    private readonly HttpClient _client = new();

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

        _funcProcess = Process.Start(new ProcessStartInfo
        {
            FileName = "func",
            Arguments = "start --port 7071",
            WorkingDirectory = Path.GetFullPath("../../../HttpTriggerDemo"),
            EnvironmentVariables =
            {
                ["AzureWebJobsStorage"] = _azurite.GetConnectionString(),
                ["FUNCTIONS_WORKER_RUNTIME"] = "dotnet-isolated"
            },
            RedirectStandardOutput = true,
            UseShellExecute = false
        });

        await WaitForHostReady(_funcProcess, TimeSpan.FromSeconds(30));
    }

    [Fact]
    public async Task CreateOrder_WithValidRequest_Returns201()
    {
        var response = await _client.PostAsJsonAsync(
            "http://localhost:7071/api/orders",
            new CreateOrderRequest("WIDGET-42", 3));

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

    private static async Task WaitForHostReady(Process process, TimeSpan timeout)
    {
        var ready = new TaskCompletionSource<bool>();
        process.OutputDataReceived += (_, e) =>
        {
            if (e.Data?.Contains("Host started") == true)
                ready.TrySetResult(true);
        };
        process.BeginOutputReadLine();
        await ready.Task.WaitAsync(timeout);
    }

    public async Task DisposeAsync()
    {
        _funcProcess?.Kill(entireProcessTree: true);
        await _azurite.DisposeAsync();
        _client.Dispose();
    }
}

func must be on the PATH. CI pipelines need npm install -g azure-functions-core-tools@4 before these tests run: it's a test infrastructure dependency that bites if you assume it's there.

Kill(entireProcessTree: true) matters on Windows. func start spawns child processes; killing just the parent leaves orphaned processes holding port 7071, which causes every subsequent E2E test run in that session to hang on startup.

WaitForHostReady polls stdout for "Host started". Startup takes 3-10 seconds depending on cold JIT and machine speed. Set the timeout conservatively: a flaky timeout is harder to debug than a slow test.

Put these tests in a separate project with [Trait("Category", "E2E")] and exclude them from the fast inner development loop. They're most useful in CI as a gate before deployment, not as daily feedback during development.

Testing an event-driven function

HTTP triggers test cleanly: call the function directly, inspect the return value. Event Hub triggers are different. The function receives a batch of EventData, deserializes each message, and delegates to a service; the trigger binding itself is provided by the runtime. That runtime can run locally.

The scenario here is an IoT pipeline: devices publish sensor readings to an Event Hub, and a function consumes the batch, validates each reading, and writes to Cosmos DB.

The function

The function stays thin. Deserialize the batch, call the service, nothing else:

public class SensorReadingFunction(
    ILogger<SensorReadingFunction> logger,
    ISensorProcessor processor)
{
    [Function(nameof(SensorReadingFunction))]
    public async Task Run(
        [EventHubTrigger("sensor-readings", Connection = "EventHubConnection")]
        EventData[] events)
    {
        logger.LogInformation("Processing batch of {Count} events", events.Length);

        foreach (var eventData in events)
        {
            var reading = JsonSerializer.Deserialize<SensorReading>(eventData.Body.Span);
            if (reading is null) continue;

            await processor.ProcessAsync(reading);
        }
    }
}

The EventData[] parameter receives the batch. The function doesn't know or care how many partitions the hub has, how messages were routed, or what retry policy applies: that's the runtime's job.

Unit testing the function

Construct EventData directly with a JSON body and call Run(). No containers, no emulator:

[Fact]
public async Task Run_WithBatchOfThreeEvents_CallsProcessorThreeTimes()
{
    var processor = Substitute.For<ISensorProcessor>();
    var function = new SensorReadingFunction(NullLogger<SensorReadingFunction>.Instance, processor);

    EventData[] events =
    [
        CreateEventData(new SensorReading("device-01", 22.5, 60.0, DateTimeOffset.UtcNow)),
        CreateEventData(new SensorReading("device-02", 25.0, 55.0, DateTimeOffset.UtcNow)),
        CreateEventData(new SensorReading("device-03", 18.3, 72.0, DateTimeOffset.UtcNow)),
    ];

    await function.Run(events);

    await processor.Received(3).ProcessAsync(Arg.Any<SensorReading>());
}

private static EventData CreateEventData(SensorReading reading)
    => new(JsonSerializer.SerializeToUtf8Bytes(reading));

This catches deserialization bugs and verifies the batch loop without starting anything.

Full trigger integration test

Unit tests verify the dispatch and deserialization logic in isolation. The full pipeline test goes further: a real message flows from Event Hubs through the function and into Cosmos DB.

The fixture starts three containers in parallel (Azurite for the Functions runtime, the Event Hubs emulator, and the Cosmos DB emulator), then launches func start as a child process wired to all three. The full source is in SensorPipelineFixture.cs. The container declarations and process wiring both require non-obvious configuration.

Container configuration:

// Use latest: Core Tools 4.8 sends an API version that Azurite 3.28.0 (the Testcontainers default) rejects.
private readonly AzuriteContainer _azurite = new AzuriteBuilder()
    .WithImage("mcr.microsoft.com/azure-storage/azurite:latest")
    .Build();

// WithPortBinding pins the host port so localhost:8081 resolves from the func child process.
private readonly CosmosDbContainer _cosmos = new CosmosDbBuilder()
    .WithImage("mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview")
    .WithPortBinding(8081, 8081)
    .WithWaitStrategy(Wait.ForUnixContainer()
        .UntilMessageIsLogged("Gateway=OK, Explorer=OK"))
    .Build();

private readonly EventHubsContainer _eventHubs;

public SensorPipelineFixture()
{
    _eventHubs = new EventHubsBuilder()
        .WithAcceptLicenseAgreement(true)
        .WithConfigurationBuilder(EventHubsServiceConfiguration.Create()
            .WithEntity("sensor-readings", 2, []))
        .WithWaitStrategy(Wait.ForUnixContainer()
            .UntilMessageIsLogged("Emulator Service is Successfully Up!"))
        .Build();
}

Testcontainers pins azurite:3.28.0 as its default. Azure Functions Core Tools 4.8 sends API version 2024-08-04; Azurite 3.28.0 rejects that version with a 400. Pinning to latest resolves it.

Both the Event Hubs emulator and the Cosmos vnext-preview image are distroless: no shell, no /bin/sh. The default Testcontainers port-check wait strategy execs /bin/sh inside the container to verify the port is listening. On a distroless image, that exec fails and the strategy hangs indefinitely. UntilMessageIsLogged() watches the container's stdout stream directly, bypassing the shell dependency.

The Cosmos emulator returns its own internal address in the account metadata it sends back to clients. The test-process CosmosClient receives localhost:8081 as the endpoint and follows it there. WithPortBinding(8081, 8081) ensures that host port is pinned, so the func child process (which constructs its own CosmosClient) lands on the same address.

WithResourceMapping mounts a JSON configuration file into the Event Hubs emulator container, but it doesn't set the ServiceConfiguration property the builder reads at Build() time. The build throws at runtime. WithConfigurationBuilder uses the fluent API to set ServiceConfiguration directly, and the configuration is validated at build time.

Process wiring:

var cosmosPort = _cosmos.GetMappedPublicPort(8081);
var cosmosKey = _cosmos.GetConnectionString()
    .Split(';').First(p => p.StartsWith("AccountKey=", StringComparison.Ordinal))
    .Substring("AccountKey=".Length);

CosmosClient = new CosmosClient(
    _cosmos.GetConnectionString(),
    new CosmosClientOptions
    {
        ConnectionMode = ConnectionMode.Gateway,
        HttpClientFactory = () => new HttpClient(new CosmosEmulatorHandler(cosmosPort)),
        SerializerOptions = new CosmosSerializationOptions
        {
            PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
        }
    });

startInfo.Environment["CosmosDbConnection"] =
    $"AccountEndpoint=http://localhost:{cosmosPort}/;AccountKey={cosmosKey}";

The func child process constructs its own CosmosClient from the CosmosDbConnection environment variable; it can't share the test process's HttpClient handler across the process boundary. Passing AccountEndpoint=http://localhost:{port}/ with an explicitly extracted key gives the child process a direct HTTP connection to the emulator without needing the handler.

CosmosEmulatorHandler is an HttpMessageHandler that rewrites outgoing requests from the emulator's self-reported internal hostname to localhost:{cosmosPort}. Without it, the SDK follows the internal address the emulator returns in its account metadata and misses the container.

The full fixture also implements WaitForFunctionsHostAsync (polls localhost:7071/admin/host/status until the host responds) and DisposeAsync (kills the process tree and disposes all three containers). Both are in the full source.

The test publishes a batch and polls Cosmos DB until the document appears:

[Collection(SensorPipelineFixture.Name)]
public class SensorPipelineTests(SensorPipelineFixture fixture)
{
    [Fact]
    public async Task PublishedEvent_WithValidReading_AppearsInCosmosDb()
    {
        var reading = new SensorReading(
            DeviceId: $"device-{Guid.NewGuid():N}",
            Temperature: 23.4,
            Humidity: 58.0,
            Timestamp: DateTimeOffset.UtcNow);

        var batch = await fixture.ProducerClient.CreateBatchAsync();
        batch.TryAdd(new EventData(JsonSerializer.SerializeToUtf8Bytes(reading)));
        await fixture.ProducerClient.SendAsync(batch);

        var container = fixture.CosmosClient.GetContainer("SensorData", "readings");
        var deadline = DateTime.UtcNow.AddSeconds(30);
        List<dynamic> results = [];

        while (DateTime.UtcNow < deadline)
        {
            var query = container.GetItemQueryIterator<dynamic>(
                $"SELECT * FROM c WHERE c.deviceId = '{reading.DeviceId}'");
            results.Clear();
            while (query.HasMoreResults)
                results.AddRange(await query.ReadNextAsync());

            if (results.Count > 0) break;
            await Task.Delay(500);
        }

        Assert.Single(results);
        Assert.Equal(23.4, (double)results[0].temperature, precision: 1);
    }
}

The fixture takes 60–90 seconds to start. Run it separately from unit tests in CI using xUnit's [Collection] trait or a test filter.

Add the packages:

<PackageReference Include="Testcontainers.EventHubs" />
<PackageReference Include="Testcontainers.CosmosDb" />
<PackageReference Include="Testcontainers.Azurite" />
<PackageReference Include="Azure.Messaging.EventHubs" />
<PackageReference Include="Newtonsoft.Json" />

Cosmos SDK v3 requires Newtonsoft.Json at runtime via an internal dependency. Omitting it produces a FileNotFoundException at startup with no message connecting it to Cosmos.

What can't be emulated locally

Azurite and func start cover wiring and trigger dispatch. Some behaviors only emerge in Azure.

Cold starts. Local tests keep the host warm throughout the run. Consumption plan cold starts in Azure hit 500ms-2s for .NET depending on deployment size. If your SLA depends on p99 latency, that gap only shows in production traffic — local tests give you no signal on it.

Managed identity credential resolution. DefaultAzureCredential falls through a chain of credential sources. Locally it uses developer machine credentials or environment variables. In Azure it uses the Managed Identity endpoint. A misconfigured client ID or missing role assignment won't surface until the function runs with a real identity attached. The local credential chain doesn't exercise the same code path.

Scale-out behavior. func start runs one worker. Azure scales to N workers based on trigger backlog. Race conditions, partition contention, and shared-state bugs appear only under concurrent load across multiple instances. No local setup replicates this.

KEDA-based scaling decisions. Event Hub and Service Bus triggers scale based on message lag, but the scaling decisions come from the infrastructure, not the worker process. There's no local equivalent for how Azure routes partitions across workers as instances scale up.

The useful takeaway: unit tests and integration tests give fast, reliable feedback on logic and wiring. They don't give confidence about latency under cold conditions, behavior at scale, or cloud-managed auth. Build those signals from production observability (Application Insights, structured logs, alert rules), not from test infrastructure.

Patterns that cause pain

A few mistakes appear repeatedly in Azure Functions test suites.

Asserting on log messages. Substitute.For<ILogger<T>>() lets you verify that specific log calls were made. Don't. Log messages are implementation details: they change wording, get split into multiple calls, or get removed during refactoring. When they do, your test breaks without any behavior change. Use NullLogger<T>.Instance for services and only substitute loggers when logging output is the actual behavior under test (which is almost never).

Reaching into the runtime from unit tests. [HttpTrigger], [FromBody], and [QueueTrigger] are metadata for the runtime to read. They don't execute during a direct method call. Trying to test that binding attributes are present, or that the runtime would route correctly, puts you in the business of testing the Functions SDK rather than your code. The routing table lives in the host config; your job is to test what happens once the host calls your method.

Using constructors for container lifecycle. xUnit creates test class instances before running tests, but StartAsync() is async. Initializing a AzuriteContainer in a constructor blocks the thread and causes tests to hang silently. Always use IAsyncLifetime: InitializeAsync for startup, DisposeAsync for teardown.

Testing the service layer twice. Once you have thorough OrderServiceTests, the function-level tests (OrderFunctionTests) should only cover the HTTP response mapping: does a successful result return 201, does a failure return 400. Repeating the validation and business logic assertions at the function level creates duplicate coverage that breaks together whenever the service contract changes.

Choosing your testing strategy

Layer	Approach	Infrastructure needed
Service logic	Unit test	None
Function routing	Unit test	None
DI wiring + middleware	HostBuilder trick	None (gRPC stripped)
Data layer round-trips	Testcontainers (SQL/Postgres/Azurite)	Docker
Trigger dispatch	`func start` + Azurite	Core Tools + Docker
Full pipeline	Testcontainers Docker image	Docker

Start from the top and stop as soon as the tests cover the risk you're managing. For most business logic, unit tests against the service layer are enough. The function class tests add a few minutes of coverage for the HTTP response shapes. Integration and E2E tests are worth the infrastructure cost only when you need to verify wiring, real database behavior, or trigger dispatch.

Do you unit test your function class directly, or do you treat the service layer as the boundary and skip function-level tests entirely?

Configuration Done Right: Settings, Secrets, and Key Vault

Martin Oehlert — Fri, 13 Mar 2026 05:43:09 +0000

You add a Service Bus connection string to appsettings.json. You deploy. The trigger fails at startup with something like:

Microsoft.Azure.WebJobs.Host.Listeners.FunctionListenerException:
The listener for function 'ProcessMessage' was unable to start.
Microsoft.Azure.WebJobs.ServiceBus.Listeners.ServiceBusListener:
Connection string not found.

Your code reads it fine. But the trigger cannot start because the host never sees appsettings.json.

Azure Functions has two distinct configuration surfaces that solve different problems:

The host process (func.exe) resolves trigger and binding connections from environment variables.
The worker process (your .NET code) reads IConfiguration, which includes appsettings.json, environment variables, and any other sources you add.

These two processes share environment variables but nothing else. This article covers how to configure each correctly, how to move secrets to Key Vault without changing your code, and how to use the options pattern for strongly-typed settings.

All code from this article is available in the azure-functions-samples repository under ConfigurationDemo/.

local.settings.json

In local development, local.settings.json is how you supply environment variables to both processes simultaneously. Core Tools (func.exe) reads this file at startup and injects every entry in the Values section as a process environment variable before launching the worker.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "ServiceBusConnection": "Endpoint=sb://...",
    "Api__BaseUrl": "https://api.example.com",
    "Api__TimeoutSeconds": "30"
  }
}

Everything in Values is a flat string pair, no nesting. For hierarchical settings, use double underscore as the separator: Api__BaseUrl becomes Api:BaseUrl in IConfiguration. All values are strings; the configuration binder converts them to the correct type when binding to options classes.

The ConnectionStrings section is a trap. It exists for ORMs like Entity Framework that expect connection strings under ConnectionStrings:*. Core Tools loads these with a ConnectionStrings: prefix — so ConnectionStrings.MyDb becomes the environment variable ConnectionStrings:MyDb. The Functions host looks for binding connections by their bare name. Put a Service Bus or Storage connection string in ConnectionStrings and the trigger cannot find it, even though your application code can read it fine with configuration.GetConnectionString("MyDb").

The rule: trigger and binding connections go in Values, always.

Azure ignores this file entirely. It is consumed only by Core Tools locally. When you deploy, you configure settings separately in the portal, via CLI, or in Bicep. If you use func azure functionapp publish --publish-local-settings, only the Values section is copied. The ConnectionStrings section is never published — another reason to avoid it.

Add local.settings.json to .gitignore. The Functions project template does this automatically, but verify it before your first commit. This file will contain connection strings, API keys, and storage credentials.

Azure App Settings

In Azure, every Application Setting is an environment variable injected into the host process. The Functions runtime treats them identically to what local.settings.json provides locally.

The portal lists them under Settings > Environment Variables > App settings. Values are encrypted at rest and masked in the UI. Any change to Application Settings causes the function app to restart.

Use the Application Settings blade, not the Connection strings blade. The Connection strings section in the portal adds a type prefix to the environment variable name. A custom connection string named ServiceBus becomes CUSTOMCONNSTR_ServiceBus in the environment. The Service Bus trigger looking for ServiceBus will not find it.

The Connection strings portal section exists for ASP.NET compatibility. For Azure Functions, put everything in Application Settings.

Hierarchical settings

Flat environment variables do not support nesting. The convention on Azure (which runs on Linux) is to use double underscore as the hierarchy separator:

App Setting name	`IConfiguration` key
`Api__BaseUrl`	`Api:BaseUrl`
`Api__TimeoutSeconds`	`Api:TimeoutSeconds`

Colon (:) works as a separator on Windows only. Double underscore works on both platforms. Always use __ in App Setting names to ensure your functions run correctly whether the app is on a Windows or Linux hosting plan.

Slot settings

Deployment slots each have their own App Settings. By default, settings swap along with the code when you swap slots. Slot settings (sticky settings) stay with the slot and do not swap.

The common use case: staging and production connect to different databases or service bus namespaces. Mark those connection strings as slot settings so a staging deployment cannot accidentally point production code at the staging database.

To mark a setting as sticky, check Deployment slot setting when editing it in the portal. In Bicep, set "slotSetting": true on the app setting object.

One gotcha: a sticky setting must exist in every slot involved in a swap. If a sticky setting exists in staging but not in production, and you swap, the setting disappears from staging after the swap. Create the setting (with the appropriate value for each environment) in every slot before you start using sticky settings.

Key Vault references

Key Vault references let you store secrets in Azure Key Vault and reference them from App Settings. The Functions host resolves the reference at startup. Your code reads the setting with the same IConfiguration["MyKey"] call it has always used.

The reference syntax in the App Setting value:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/ApiKey/)

Or by name, if the Key Vault is in the same subscription:

@Microsoft.KeyVault(VaultName=myvault;SecretName=ApiKey)

Both forms produce identical behavior at runtime. Omit the secret version from the URI to always get the latest version. The platform caches the resolved value and re-fetches it every 24 hours. Rotating a secret takes effect automatically within that window without a deployment or restart.

Failed references are silent. If the reference cannot be resolved (wrong vault name, missing permissions, deleted secret), the App Setting receives the literal reference string as its value: @Microsoft.KeyVault(...). This propagates through to your code, which typically throws because it receives an unexpected format instead of the secret value. To diagnose: open the setting in the portal and look for an error status indicator in the edit dialog. In the Azure portal, Platform features > Diagnose and solve problems also has a Key Vault Application Settings Diagnostics detector.

Managed identity setup

The function app needs permission to read secrets from the vault. The recommended approach is a system-assigned managed identity.

Enable it in the portal under Settings > Identity > System assigned > Status: On. Via CLI:

az webapp identity assign \
  --resource-group <rg> \
  --name <app-name>

Then assign the Key Vault Secrets User role to the identity on the vault:

az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee "<principalId>" \
  --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>"

The --assignee value is the principalId from the identity assignment output, not the client ID and not the app's resource ID.

Key Vault Secrets User, not Contributor. The Contributor role manages the vault as an Azure resource (creating, deleting, modifying it). It does not grant access to read secret values. Key Vault Secrets User grants data-plane read access to secrets. These are separate role planes and are frequently confused.

Creating a vault with RBAC enabled

az keyvault create \
  --name "<vault-name>" \
  --resource-group "<rg>" \
  --location "eastus" \
  --enable-rbac-authorization true

The --enable-rbac-authorization true flag is important. Without it, the vault uses the legacy access policy model. Microsoft's current guidance is to use RBAC for all new vaults. The access policy model has a privilege escalation risk: any user with Contributor on the vault can modify access policies to grant themselves secret access. Under RBAC, only Owner and User Access Administrator can modify role assignments.

Once the vault exists, add a secret:

az keyvault secret set \
  --vault-name "<vault-name>" \
  --name "ApiKey" \
  --value "<your-secret>"

Local development

Key Vault references are a portal-level feature. They do not apply locally. For local development, put the actual secret values directly in local.settings.json:

{
  "Values": {
    "ApiKey": "dev-key-here"
  }
}

The app code does not change. The same configuration["ApiKey"] call works locally (reading from the environment variable injected by Core Tools) and in Azure (reading from the Key Vault reference resolved by the platform).

If your team needs local access to the actual Key Vault for testing, use DefaultAzureCredential in your service registration and run az login with an account that has Key Vault Secrets User on the vault. The credential chain tries Azure CLI authentication, so the logged-in developer account gets used automatically.

Strongly-typed configuration with the options pattern

Reading configuration with configuration["MyKey"] works but gives you a stringly-typed API with no validation and no structure. The options pattern solves this by binding a configuration section to a typed class.

Define the options class:

public class ApiOptions
{
    [Required]
    public required string BaseUrl { get; init; }

    [Range(1, 300)]
    public int TimeoutSeconds { get; init; } = 30;
}

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddOptions<ApiOptions>()
    .BindConfiguration("Api")
    .ValidateDataAnnotations()
    .ValidateOnStart();

builder.Build().Run();

BindConfiguration("Api") binds from the Api section of IConfiguration. After GetSection strips the prefix, ApiOptions.BaseUrl maps to the Api:BaseUrl key, which in turn comes from the Api__BaseUrl environment variable. The same property name works whether the setting originates from appsettings.json, local.settings.json, or an Azure App Setting.

Inject the options into a function class:

public class ProcessOrderFunction(IOptions<ApiOptions> options)
{
    private readonly ApiOptions _api = options.Value;

    [Function("ProcessOrder")]
    public async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        // _api.BaseUrl and _api.TimeoutSeconds are validated and available
        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(_api.TimeoutSeconds) };
        var response = await client.GetAsync($"{_api.BaseUrl}/orders");
        return new OkResult();
    }
}

ValidateOnStart

Without ValidateOnStart(), validation fires when .Value is first accessed. A misconfigured but rarely-invoked function can pass through a cold start and fail only at runtime, when you least expect it. With ValidateOnStart(), the host throws OptionsValidationException during startup and refuses to run:

Microsoft.Extensions.Options.OptionsValidationException:
  DataAnnotation validation failed for 'ApiOptions' members:
    'BaseUrl' with the error: 'The BaseUrl field is required.'

This converts a silent runtime failure into an explicit startup failure, which is much easier to diagnose.

IOptions vs IOptionsSnapshot vs IOptionsMonitor

Use IOptions<T> in Azure Functions. The value is cached per singleton lifetime, which is correct: App Settings do not change at runtime without a restart, and a restart rebuilds the singleton anyway.

IOptionsSnapshot<T> is Scoped. Injecting it into a singleton throws at runtime. Functions does not have the same clear scope-per-request lifecycle as ASP.NET Core, so IOptionsSnapshot<T> causes subtle failures.

IOptionsMonitor<T> is safe in singletons and works if you need to respond to live configuration changes (for example, from Azure App Configuration with a refresh sentinel). For standard App Settings, it is more complexity than the scenario requires.

local.settings.json for options

The Values section is a flat dictionary. To represent the Api section locally, use the __ separator:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "Api__BaseUrl": "https://api.example.com",
    "Api__TimeoutSeconds": "30"
  }
}

In Azure, create App Settings with the same names: Api__BaseUrl and Api__TimeoutSeconds. The binding is identical in both environments.

The three-layer mental model

When a configuration problem comes up, the question to ask is: which process needs this value?

Trigger and binding connections are resolved by the host process. They must be environment variables: either a Values entry in local.settings.json, an Azure App Setting, or a Key Vault reference on an App Setting. No other configuration source reaches the host.

Application settings (anything your code reads via IConfiguration) come from the full configuration pipeline: environment variables, appsettings.json, appsettings.{Environment}.json, and any sources you add in Program.cs. Because environment variables are part of this pipeline, all App Settings are also available in IConfiguration.

Secrets live in Key Vault and are surfaced as App Settings via the reference syntax. Your code sees them as ordinary environment variables and reads them through IConfiguration like any other setting.

The full working ConfigurationDemo project — ApiOptions, registration in Program.cs, and ProcessOrderFunction — is in the azure-functions-samples repository. Clone it, copy local.settings.json.example to local.settings.json, and run func start to see ValidateOnStart in action.

What do you use to manage secrets in your Azure Functions projects: Key Vault references, Azure App Configuration, or something else? Drop it in the comments.

AzureFunctions #DotNet #Azure #Security #KeyVault

Understanding the Isolated Worker Model

Martin Oehlert — Fri, 06 Mar 2026 07:21:24 +0000

The problem the isolated model solves

You add a NuGet reference to Newtonsoft.Json 13.0. Your code compiles. Your unit tests pass. You deploy to Azure Functions, and at runtime, your function silently uses version 12.0.3.

No error. No warning. Just the host's copy of the assembly winning the load, because your function code and the Azure Functions runtime shared a single process.

This was the in-process model, and for years it was the only way to build .NET Azure Functions. Your function assemblies loaded directly into the same CLR instance as the Functions host. The host pinned its own versions of core packages: Newtonsoft.Json, Microsoft.Extensions.DependencyInjection, ASP.NET Core libraries, and dozens of others. If your code depended on a different version, the host's version won at load time. You had no way to override it.

The version conflict problem went beyond JSON serialization. The host determined which .NET runtime your code ran on. When .NET 7 shipped, you could not target it until the Functions team updated the host. When .NET 8 arrived, the same waiting game. Your application's target framework was not your decision; it was the host's.

Startup control was equally limited. The in-process model offered FunctionsStartup as an extension point for dependency injection:

[assembly: FunctionsStartup(typeof(MyStartup))]

public class MyStartup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton<IOrderService, OrderService>();
    }
}

This gave you a DI container, but nothing else. No middleware pipeline. No request/response interception. No control over serialization settings, logging providers, or configuration sources beyond what the host exposed. If you wanted to add authentication middleware, or swap the JSON serializer for System.Text.Json, or wire up OpenTelemetry tracing, you were working against the grain.

FunctionsStartup was a workaround bolted onto a hosting model that was never designed for extensibility. The isolated worker model replaced it entirely.

Two processes, one function app

The isolated model splits your function app into two separate OS processes. The Azure Functions host (func.exe) handles triggers, bindings, and routing. Your code runs in a separate worker process (dotnet.exe) with its own CLR, its own assembly loader, and its own dependency graph.

A single environment variable controls this split. Setting FUNCTIONS_WORKER_RUNTIME to dotnet-isolated tells the host to spawn a worker process instead of loading your assemblies directly.

Azure Functions Host (func.exe)
  ├── Trigger listeners (HTTP, Service Bus, Event Hub...)
  ├── Binding infrastructure
  ├── host.json configuration
  └── gRPC server
         ↕ gRPC / Protobuf over HTTP/2
Worker Process (dotnet.exe / your app)
  ├── Program.cs bootstrap
  ├── Your DI container
  ├── Your middleware pipeline
  └── Your function code

The two processes communicate over gRPC using Protocol Buffers serialized over HTTP/2. When a trigger fires (an HTTP request arrives, a Service Bus message lands), the host serializes the trigger data into a Protobuf message and sends it to the worker. The worker executes your function, serializes the result, and sends it back.

These C4 diagrams show the two-process architecture in more detail:

Your Program.cs sets up the gRPC client, DI container, and middleware pipeline in one place:

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.UseMiddleware<ExceptionHandlingMiddleware>();
builder.UseMiddleware<CorrelationIdMiddleware>();

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights()
    .AddSingleton<IOrderService, OrderService>();

builder.Build().Run();

ConfigureFunctionsWebApplication() registers the gRPC client that talks back to the host, enables ASP.NET Core integration for HTTP triggers, and gives you the middleware pipeline shown above. If you do not need HTTP trigger support, ConfigureFunctionsWorkerDefaults() does the same setup without the ASP.NET Core integration.

Because each process loads its own assemblies independently, the version conflict problem disappears. Your worker targets .NET 10 and references Newtonsoft.Json 13.0.3? That is what runs. The host still uses whatever versions it needs internally, and the two never collide.

The trade-off is that every function invocation crosses a process boundary. The host serializes trigger data, sends it over gRPC, and the worker deserializes it. On the same machine, the latency cost is negligible for most workloads. Where you will notice it is cold starts: the runtime now needs to spin up two processes instead of one. For high-throughput, latency-sensitive functions that fire thousands of times per second, measure the overhead in your specific scenario. For the vast majority of production workloads (processing orders, handling webhooks, running scheduled cleanup jobs), the isolation is worth far more than the milliseconds it costs.

What you gain

The isolated worker model removes real constraints that made the in-process model frustrating in production.

No more assembly conflicts

Your worker runs in its own process with its own dependency graph. The host loads whatever versions it needs; your application loads whatever versions you reference. Two processes, two sets of assemblies, zero conflicts. The Newtonsoft.Json problem from the opening of this article cannot happen in the isolated model.

Full startup control via Program.cs

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddSingleton<IOrderService, OrderService>()
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Build().Run();

This replaces the [assembly: FunctionsStartup(typeof(MyStartup))] attribute and the Startup class you had to wire up in the in-process model. The whole application now bootstraps through the .NET Generic Host, the same pattern you already know from ASP.NET Core and worker services.

FunctionsApplication.CreateBuilder(args) sets up the host builder with Functions-specific defaults. ConfigureFunctionsWebApplication() enables ASP.NET Core integration so your HTTP triggers can work with HttpRequest and HttpResponse directly instead of the SDK's custom types.

The Services block is standard dependency injection. AddSingleton<IOrderService, OrderService>() registers your own service. AddApplicationInsightsTelemetryWorkerService() and ConfigureFunctionsApplicationInsights() wire up telemetry for the worker process (both are needed: the first adds the base SDK, the second configures Functions-specific log filtering).

builder.Build().Run() starts the worker and connects it to the host over gRPC. If you have written a .NET 8 web API, this code should look familiar, because it is the same hosting model.

Middleware pipeline

The in-process model had no middleware. If you needed cross-cutting behavior (logging correlation IDs, catching unhandled exceptions, validating tokens) you were stuck wiring it through WebJobs SDK extension points or scattering try/catch blocks across every function.

The isolated model gives you an ASP.NET Core-style pipeline around every function invocation:

builder.UseMiddleware<CorrelationIdMiddleware>();
builder.UseMiddleware<ExceptionHandlingMiddleware>();

Each middleware runs in order before the function executes, then unwinds in reverse order after. You build one by implementing IFunctionsWorkerMiddleware:

public class CorrelationIdMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        // Runs before the function
        var correlationId = Guid.NewGuid().ToString();

        await next(context);

        // Runs after the function
    }
}

FunctionContext gives you access to the invocation metadata, bindings, and the IServiceProvider. The next delegate calls either the next middleware in the chain or the function itself. Everything before await next(context) runs on the way in; everything after runs on the way out.

In production, you would typically read an incoming correlation ID from a header or message property, fall back to generating one if it is missing, then stash it in context.Items so the function and downstream services can pick it up. Exception-handling middleware wraps the next call in a try/catch, logs the failure with structured context, and returns a consistent error response instead of letting the host surface a generic 500.

.NET version flexibility

The worker process runs whatever .NET version you target, independently of the host. The host stays on its own runtime; your code stays on yours.

Today, the isolated model supports .NET 8, .NET 9, .NET 10, and even .NET Framework 4.8 (for teams that cannot migrate legacy libraries). The in-process model was capped at .NET 8 with v4 of the Functions runtime and will never support .NET 9 or later. When .NET 12 ships, you will update your TargetFramework, redeploy, and move on. No waiting for the Azure Functions team to update the host.

Your release cycle and the host's release cycle are decoupled. You upgrade on your schedule.

What changes from in-process

Most of the migration is mechanical. The conceptual model shifts, but the actual code changes follow a predictable pattern. Once you have seen each one, you can work through a real codebase systematically.

The function attribute

// In-process
[FunctionName("ProcessOrder")]
public IActionResult Run([HttpTrigger] HttpRequest req, ILogger log)

// Isolated (with ASP.NET Core integration)
[Function("ProcessOrder")]
public IActionResult Run([HttpTrigger] HttpRequest req)

[FunctionName] comes from the WebJobs SDK (Microsoft.Azure.WebJobs). [Function] comes from the Functions Worker SDK (Microsoft.Azure.Functions.Worker). The attribute names differ by one word, which makes a global search-and-replace dangerous: you need to update the package reference and the attribute name together, or you will reference an attribute that does not exist in your new dependencies.

HTTP types

The isolated model gives you two ways to handle HTTP triggers, and the difference matters:

Option	Types used	When to choose
ASP.NET Core integration	`HttpRequest` / `IActionResult`	New projects, or migrating from in-process
Built-in model	`HttpRequestData` / `HttpResponseData`	Legacy compatibility only

ASP.NET Core integration is the path to take. It means your HTTP functions look exactly like ASP.NET Core controller actions, and all the routing, model binding, and result types you already know apply. It requires two things: the Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore package, and ConfigureFunctionsWebApplication() in Program.cs instead of ConfigureFunctionsWorkerDefaults(). If you find tutorials using HttpRequestData, they predate the ASP.NET Core integration and are using the older built-in types. You can use either, but the ASP.NET Core path removes an entire class of "why does this work differently than my API controllers?" questions.

Output bindings

In-process used out parameters for output bindings. Isolated uses return values with attributes:

// In-process: out parameters
public IActionResult Run(..., out string outputMessage)

// Isolated: return value with output binding attribute
[Function("ProcessOrder")]
[QueueOutput("orders-processed")]
public string Run([QueueTrigger("orders-pending")] string message)
{
    return processedMessage;
}

The out parameter approach was a side effect of how the WebJobs SDK wired up bindings. In isolated, bindings are attributes on the return type, which makes the data flow explicit: what the function returns is what gets written to the binding.

When you need multiple outputs (for example, writing to a queue and returning an HTTP response), you define a dedicated return type:

public record MultiOutputResult(
    [property: QueueOutput("dead-letter")] string? DeadLetterMessage,
    IActionResult Response
);

Each property carries its own binding attribute. The runtime inspects the returned record and routes each value to the appropriate destination. This is more verbose than out parameters for simple cases, but it makes multi-output functions far easier to read: every output is explicit in the return type definition rather than scattered across a function signature.

Dependency injection

// In-process: FunctionsStartup + IFunctionsHostBuilder
[assembly: FunctionsStartup(typeof(Startup))]
public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton<IMyService, MyService>();
    }
}

// Isolated: Program.cs (standard Generic Host)
var builder = FunctionsApplication.CreateBuilder(args);
builder.Services.AddSingleton<IMyService, MyService>();
builder.Build().Run();

FunctionsStartup was a Functions-specific extension point built on top of the Generic Host. In isolated, there is no extension point: your function app is a Generic Host application. Program.cs is the entry point, and the Services property is a standard IServiceCollection. Delete Startup.cs, delete the Microsoft.Azure.Functions.Extensions package reference, and move your service registrations into Program.cs. There is nothing Functions-specific about how DI works after that.

ILogger injection

// In-process: ILogger passed as function parameter
public IActionResult Run(..., ILogger log)

// Isolated: inject ILogger<T> via constructor
public class OrderFunction(ILogger<OrderFunction> logger)
{
    [Function("ProcessOrder")]
    public IActionResult Run([HttpTrigger] HttpRequest req)
    {
        logger.LogInformation("Processing order");
        // ...
    }
}

In the in-process model, the runtime injected ILogger directly into the function method as a parameter. That was a WebJobs SDK feature with no equivalent in the isolated model. In isolated, your function class is an ordinary class that the DI container constructs. You inject ILogger<T> through the constructor, exactly as you would in any .NET service. The generic type parameter means your logs are automatically scoped to the class name in Application Insights.

Every function that currently takes ILogger log as a method parameter needs to become an instance class with a constructor. That is one of the more time-consuming parts of migration for large codebases.

Package references and project type

<!-- In-process -->
<OutputType>Library</OutputType>  <!-- implicit, often omitted -->
<PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.x" />

<!-- Isolated: a real executable -->
<OutputType>Exe</OutputType>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
<PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
<PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
<PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
<PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />

<OutputType>Exe</OutputType> is not optional. The isolated worker is a process that starts, connects to the host over gRPC, and runs until it is shut down. It is not a library that gets loaded into another process. The old Microsoft.NET.Sdk.Functions meta-package is replaced by separate packages: the core worker, the build SDK (which handles source generation for bindings), the HTTP ASP.NET Core extension, and two Application Insights packages.

Your binding extensions also change package namespace. Every Microsoft.Azure.WebJobs.Extensions.* package becomes a Microsoft.Azure.Functions.Worker.Extensions.* equivalent. The NuGet package names differ; the binding attributes inside them often keep the same names, which reduces the code changes needed.

Static classes become instance classes

// In-process: static class (common pattern)
public static class OrderFunction
{
    [FunctionName("ProcessOrder")]
    public static IActionResult Run([HttpTrigger] HttpRequest req, ILogger log)
    { ... }
}

// Isolated: instance class required for constructor injection
public class OrderFunction(ILogger<OrderFunction> logger)
{
    [Function("ProcessOrder")]
    public IActionResult Run([HttpTrigger] HttpRequest req)
    { ... }
}

Static function classes were idiomatic in in-process because the runtime called your method directly by reflection and supplied everything through parameters. Constructor injection is impossible on a static class, so isolated requires instance classes. The compiler will not tell you this immediately: your static class will compile fine, but the runtime will fail to instantiate it because it cannot inject dependencies into a static constructor. Make the class non-static and add a constructor for your dependencies.

JSON serialization

In-process defaulted to Newtonsoft.Json for binding serialization. Isolated defaults to System.Text.Json. This is the change most likely to produce silent runtime bugs rather than compilation errors.

[JsonProperty("field_name")] does not exist in System.Text.Json. The equivalent is [JsonPropertyName("field_name")]. CamelCase naming defaults differ between the two libraries. Null handling, reference loop handling, and enum serialization all differ. If your functions receive JSON payloads, serialize objects to queues, or return JSON from HTTP triggers, test each one end-to-end after migration. A mismatch between what your function now serializes and what downstream consumers expect will not show up at compile time.

Imperative bindings

IBinder, the in-process mechanism for creating bindings at runtime (for example, writing to a blob whose path you only know after reading a message), has no equivalent in isolated. The recommended replacement is injecting the Azure SDK client directly: BlobServiceClient, QueueClient, ServiceBusClient. This is cleaner code in either model: SDK clients are testable, type-safe, and do not require the Functions binding infrastructure to work.

The .NET 10 requirement

.NET 10 only supports the isolated model. There is no in-process support for .NET 10, and none is planned. If you are starting a new project today and targeting .NET 10, you are already using isolated by necessity; this article just explains the architecture behind it.

The support matrix makes the direction clear:

.NET version	In-process	Isolated
.NET Framework 4.8	No	Yes
.NET 8 (LTS)	Yes (final version)	Yes
.NET 9 (STS)	No	Yes
.NET 10 (LTS)	No	Yes

.NET 8 is the last version the in-process model will ever support. If your function app runs on .NET 8 today, you are already at the ceiling. Staying on in-process means staying on .NET 8 until November 2026, then losing support entirely. Migrating to isolated means you can move to .NET 10 now, get the latest runtime improvements, and upgrade again when .NET 12 arrives without any coordination with the Azure Functions team.

The November 2026 deadline

In-process model support ends on November 10, 2026. That date is not arbitrary: it aligns with the end-of-life date for .NET 8 LTS. After that point, in-process function apps receive no security patches, no bug fixes, and no platform updates. The deadline is firm.

Start your inventory now. This PowerShell script identifies every in-process function app in your subscription:

$FunctionApps = Get-AzFunctionApp

foreach ($App in $FunctionApps) {
    if ($App.Runtime -eq 'dotnet') {
        Write-Output "$($App.Name) - in-process, needs migration"
    }
}

A Runtime value of dotnet means in-process. dotnet-isolated means already migrated. Run this across every subscription where you might have deployed function apps, including non-production environments where older versions sometimes linger.

The migration itself is mechanical for most functions: update packages, add Program.cs, fix compilation errors, update attributes. The problem is not the mechanical work; it is the edge cases that surface during testing. A function that uses IBinder, a binding attribute with changed properties, a JSON payload that now serializes differently: each one is a small investigation. In a codebase with dozens of functions, those investigations add up.

The recommended order of attack:

Run the script above and produce a full inventory with function counts per app.
Start with the simplest apps: HTTP triggers, no output bindings, no IBinder.
Update packages and Program.cs first, then fix compilation errors function by function.
Test locally with func start before touching Azure.
Deploy to a staging slot and run your smoke tests before swapping to production.

The staging slot step matters more here than in typical deployments. When you swap, the FUNCTIONS_WORKER_RUNTIME app setting switches from dotnet to dotnet-isolated. If your code and the app setting get out of sync even briefly, the app enters an error state. Slots let you validate the new configuration in production infrastructure before making it live.

Waiting until Q3 2026 to start leaves no room for the edge cases. Start with your least critical app now, learn the migration pattern in a low-stakes context, and work forward from there.

One more thing: Flex Consumption is isolated-only

The Flex Consumption plan is Microsoft's newest Azure Functions hosting option. It scales each function independently rather than scaling the whole app, supports always-ready instances that eliminate cold starts for your busiest functions, and bills at a finer granularity than the standard Consumption plan. If any of that sounds appealing, the isolated worker model is a prerequisite.

In-process cannot run on Flex Consumption at all. The two are architecturally incompatible: Flex Consumption requires the worker process model to manage per-function scaling, and in-process has no worker process to manage.

If you are evaluating hosting options for a new function app, that decision is already made for you: Flex Consumption is isolated-only, and isolated is where all future platform investment is going. Starting on in-process today means either migrating before you can move to Flex Consumption, or accepting a hosting model that cannot take advantage of the newest platform capabilities.

Configuration: two surfaces, not one

After migration, one category of bug appears repeatedly: a developer configures something in Program.cs and it has no effect on trigger behavior. The root cause is always the same: the isolated model has two separate configuration surfaces, one for the host process and one for the worker process.

Host configuration governs triggers, bindings, and scaling. Two sources feed it:

host.json: extension settings, retry policies, connection concurrency, scale behavior.
Environment variables and Azure App Service application settings: connection strings that the host uses to connect to Service Bus, Storage, Event Hub, and other binding sources.

Worker configuration governs your application code. Two sources feed it:

appsettings.json: loaded automatically by FunctionsApplication.CreateBuilder(), accessible through IConfiguration.
Anything you wire up in Program.cs: additional configuration providers, secrets, feature flags.

The critical rule: connection strings for bindings go in environment variables (or App Service application settings in production), not in appsettings.json. The host process that initializes the Service Bus trigger listener or the Storage queue poller reads from environment variables. It cannot read your worker's appsettings.json. A connection string that lives only in appsettings.json will work fine for any code in your worker that reads it directly (for example, an Azure SDK client you construct manually) but will cause the binding itself to fail at startup with a cryptic "missing connection string" error.

Locally, local.settings.json maps its Values section into environment variables when the Functions host starts, which is why everything works in local development even when you have not thought carefully about this split. In Azure, you configure application settings in the portal or via deployment scripts, and they become environment variables for both processes.

Migration gotchas worth knowing in advance

The following issues are not obvious from the migration documentation and tend to surface late, when you are integrating and testing rather than making mechanical code changes.

ILogger as a method parameter is gone. The runtime no longer injects it. Every function that currently takes ILogger log as a parameter needs to become an instance class with a constructor that accepts ILogger<T>. In large codebases, this touches many files.
JSON serialization changes silently. Moving from Newtonsoft.Json to System.Text.Json changes how your bindings serialize and deserialize data. [JsonProperty] becomes [JsonPropertyName]. Null values, camelCase defaults, and enum handling all differ. A function that processes messages from a queue may silently start deserializing them incorrectly if the attribute names change. Test every binding that touches JSON.
Application Insights log filtering moves from host.json to Program.cs. Log levels configured under logging.logLevel in host.json no longer apply to code running in the worker process. To filter worker logs, call ConfigureFunctionsApplicationInsights() in Program.cs and configure the log level there. Without this, you may find your worker logs missing from Application Insights, or flooded with debug output you expected to filter out.
IAsyncCollector<T> has no direct equivalent. If your functions write multiple messages to a queue or table using IAsyncCollector<T>, replace it with an array property on a dedicated return type. IAsyncCollector<string> becomes string[] on a record that your function returns.
Blob binding attribute properties changed. [Blob("container/path", FileAccess.Write)] does not exist in the isolated extension. The equivalent is [BlobOutput("container/path")]. The FileAccess enum property was removed; the direction is now expressed by whether you use [BlobInput] or [BlobOutput]. This is a compilation error, which means you will catch it, but expect to update every blob binding attribute.
Custom configuration in Program.cs is invisible to the host. If you read a connection string from appsettings.json in Program.cs and wire it up to a service, that configuration does not flow to the binding runtime. Trigger connections must come from environment variables. This is a duplicate of the two-surfaces rule above, but it is worth restating because it manifests as a confusing runtime error rather than a compilation failure.
FUNCTIONS_WORKER_RUNTIME and the deployed code must change together. If the app setting in Azure says dotnet but you deploy isolated code (or the reverse), the function app enters an error state on startup. Use deployment slots to change the app setting and deploy the code atomically, then validate in staging before swapping to production.

Where to go from here

The isolated model is the foundation everything else in this series sits on. The HTTP trigger patterns in Part 2 and the timer, queue, and blob triggers in Part 3 all assumed isolated; now you know why those patterns look the way they do. The local development setup in Part 4 works as it does because the worker process can be debugged independently of the host. The architecture is not incidental; it shapes every practical detail.

If you are migrating an existing in-process app, the Microsoft migration guide walks through the steps with tooling support including a migration tool that handles some of the mechanical changes automatically. Use it as a checklist, but read through the sections on JSON serialization and Application Insights filtering before you declare the migration done: those two areas produce the most post-migration bugs.

If you are starting a new project, start on isolated and .NET 10. The in-process model has no future, and building on it today means doing this migration under deadline pressure later.

Which part of the migration gave you the most trouble, or are you starting fresh with isolated from day one?

Local Development Setup: Tools, Debugging, and Hot Reload

Martin Oehlert — Fri, 27 Feb 2026 06:32:38 +0000

You add a breakpoint. You press F5. The function executes. The breakpoint never fires.

This is the most common introduction to Azure Functions local development. The reason is non-obvious: when you debug a .NET isolated worker function, two separate processes run. Your debugger attached to the host process (func.exe) instead of the worker process (dotnet.exe), which is where your code actually executes.

local.settings.json causes a different kind of confusion. Unlike appsettings.json, it injects environment variables: put a connection string in the wrong section and your bindings silently break. Azurite is a related trap: timer, queue, and blob triggers all use Azure Storage internally, so the emulator has to be running before those trigger types will initialize, even if your function code touches no storage directly.

This covers the full local setup for Azure Functions with .NET 10 and the isolated worker model. What's not here: deployment, Application Insights (that's Part 9), or unit testing (Part 7).

What you need: three installs

Three things have to be installed and working before you can run any Azure Function locally.

A. .NET 10 SDK

dotnet --version   # expect 10.x.x
dotnet --list-sdks # confirm 10.x is listed

If you followed Parts 1-3, this is already done. If not, download from dot.net.

B. Azure Functions Core Tools v4

Core Tools provides the func CLI that starts the local Functions host. Install it with your package manager:

macOS: brew tap azure/functions && brew install azure-functions-core-tools@4
Windows: winget install Microsoft.Azure.FunctionsCoreTools or the MSI download (64-bit required for VS Code debugging)
Linux: APT install from Microsoft package feeds (see the official instructions)
npm (cross-platform): npm i -g azure-functions-core-tools@4 --unsafe-perm true

A note on the npm option for Windows: if you are using Microsoft.Azure.Functions.Worker.Sdk 2.x, which enables dotnet run support, the npm Core Tools installation does not work correctly for that workflow. Use the winget or MSI install instead.

func --version   # expect 4.x.x

C. Azurite

Azurite emulates Azure Blob, Queue, and Table storage locally. Install it once; you will need it running for every non-HTTP function.

VS Code extension (recommended for VS Code users): search "Azurite" in the Extensions panel, or install Azurite.azurite directly
npm: npm install -g azurite
Docker: docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite
Visual Studio 2026: Azurite is bundled and starts automatically when you press F5

The old Azure Storage Emulator is deprecated. If you see references to it in older articles or documentation, ignore them.

Verification

Run this sequence to confirm everything is wired up correctly:

dotnet --version
func --version
# Start Azurite: either the VS Code extension (Command Palette: "Azurite: Start") or `azurite` in a terminal
func init TestProj --worker-runtime dotnet-isolated --target-framework net10.0
cd TestProj
func start
# Should print: "Host lock lease acquired" with no errors

If you see SocketException: Unable to connect to the remote server instead of the lock lease message, Azurite is not running. Start it first, then retry func start.

The two-process model

This is the section most local dev tutorials skip, which is why "my breakpoint won't fire" is such a common question.

In the isolated worker model, two separate processes run every time you start a debug session:

┌──────────────────────────────────────────┐
│   func.exe  (the Functions host)         │
│   - Manages triggers                     │
│   - Handles bindings                     │
│   - Routes HTTP requests                 │
│   - Runs on port 7071                    │
└──────────────────────┬───────────────────┘
                       │ gRPC
                       │
┌──────────────────────┴───────────────────┐
│   dotnet.exe  (your worker)              │
│   - Runs your actual function code       │
│   - Gets invoked by the host via gRPC    │
│   - This is where breakpoints fire       │
└──────────────────────────────────────────┘

func.exe is the Functions runtime: it manages triggers, handles bindings, and routes incoming requests. dotnet.exe is your application: it receives invocation requests from the host over gRPC and runs your actual function code. Breakpoints live in dotnet.exe, not func.exe.

This matters for debugging in two ways. First, your debugger must attach to the worker process (dotnet.exe), not to func.exe. This is why the launch.json the Azure Functions extension generates uses "request": "attach" rather than "request": "launch", and why the process ID is set to ${command:azureFunctions.pickProcess} instead of a static value. Second, the two processes produce separate log streams with separate configuration: host.json controls what func.exe logs, while your ILogger<T> calls are configured on the worker side. Changing one does not affect the other.

For comparison: the deprecated in-process model runs everything in a single process. One process, one debugger attach target. That simplicity is gone with the isolated model, but the isolation is what allows it to run on .NET 10 instead of being locked to .NET 8.

local.settings.json: not config, environment variables

A common mental model for local.settings.json is that it works like appsettings.json. It does not.

Everything in the Values section is read by Core Tools at startup and injected as process environment variables into both func.exe and the worker process. That is the entire job of this file when running locally. In Azure, there is no local.settings.json at all: the App Settings page in the portal (or the equivalent in Bicep/ARM/Terraform) sets those same environment variables directly on the hosted function app.

File structure:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "MyQueueConnection": "UseDevelopmentStorage=true",
    "MyServiceBusConnection": "<real-sb-connection-string>"
  },
  "Host": {
    "LocalHttpPort": 7071,
    "CORS": "*",
    "CORSCredentials": false
  },
  "ConnectionStrings": {
    "AppDb": "Server=localhost;Database=MyApp;Trusted_Connection=True;"
  }
}

Two keys in Values are required for every project:

FUNCTIONS_WORKER_RUNTIME: must be "dotnet-isolated" (not "dotnet", which is the in-process value; using it causes confusing startup failures)
AzureWebJobsStorage: required for every trigger type except HTTP. The host uses this storage account for timer leases, key management, and Durable Functions. Set to "UseDevelopmentStorage=true" when Azurite is running.

The ConnectionStrings section gotcha

ConnectionStrings is for Entity Framework and similar frameworks that call IConfiguration.GetConnectionString("Name"). It is not for Functions trigger and binding configuration. If you put your Service Bus or Queue connection string here, the binding's Connection property won't find it, and the error message won't point you at the right place. All binding connection strings must go in Values.

Why the file is gitignored

Even if your local values only point at Azurite today, a real connection string will appear in this file at some point, whether you add it or a teammate does. Once committed, it lives in git history. The .gitignore and .funcignore that func init generates both exclude local.settings.json from the start.

Sharing the structure with the team

The standard approach: commit a local.settings.json.example file with the same structure but placeholder values. New team members copy it to local.settings.json and fill in the real values.

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "ServiceBusConnection": "<your-service-bus-connection-string>"
  }
}

Document in the README which values work with Azurite and which require a real Azure service. Your teammates will thank you the first time they clone the repo.

Reading values in code

Direct access anywhere in your code:

var value = Environment.GetEnvironmentVariable("MyKey");

The recommended approach: inject IConfiguration and read by key name. Since the values are environment variables, the key name is the exact string in Values:

public class OrderProcessor
{
    private readonly IConfiguration _config;

    public OrderProcessor(IConfiguration config)
    {
        _config = config;
    }

    public void Process()
    {
        var connStr = _config["MyQueueConnection"];
    }
}

Part 6 covers structuring values for testability with IOptions<T>, including the double-underscore separator needed for nested configuration in environment variables.

Azurite: your local storage account

Azurite emulates the three Azure Storage services locally: Blob, Queue, and Table. Azure Functions uses these services internally, which is why Azurite has to be running even if your function code does not touch storage directly.

Why the host needs storage

The Functions host uses Azure Storage for:

Timer trigger lease management: prevents duplicate executions when multiple instances run
Function key storage: host keys and function keys are persisted in blob storage
Durable Functions task hub: state and message coordination
Event Hubs checkpoints: tracks which events have been processed

AzureWebJobsStorage in local.settings.json is the connection string for this internal storage use. Only pure HTTP-only projects can skip it. Everything else needs Azurite running first.

Which service maps to which trigger

Azurite service	Port	Used by
Blob service	10000	Blob trigger, Blob input/output bindings, host key storage
Queue service	10001	Queue trigger, Queue output binding, Durable Functions activity queue
Table service	10002	Table input/output bindings, Durable Functions instance state

Azurite Table Storage is still in preview as of February 2026. It works for most local development scenarios but is not production-equivalent.

You can start individual services if you want to be selective: azurite-blob, azurite-queue, or azurite-table as separate commands. From the VS Code Command Palette: Azurite: Start Blob Service, Azurite: Start Queue Service, etc.

Connection strings

The shorthand that works when Azurite runs on the default ports:

UseDevelopmentStorage=true

The full explicit form, needed when Azurite is in Docker or using non-default ports:

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;

The devstoreaccount1 account name and the key above are the public well-known Azurite credentials, the same for every developer. They carry no security value.

Common gotchas

Port conflicts: if ports 10000, 10001, or 10002 are already in use, Azurite fails silently or with a cryptic error. Check with lsof -i :10000 (macOS/Linux) or netstat -ano | findstr :10000 (Windows). Run with --blobPort 20000 --queuePort 20001 --tablePort 20002 to use alternate ports, and update your connection strings accordingly.
Data location: running azurite with no --location flag writes data files to the current working directory. The VS Code extension stores data in the workspace folder. Run Azurite: Clean from the Command Palette to wipe all data and start fresh, which is useful when you want to test a clean startup sequence.
Docker networking: UseDevelopmentStorage=true resolves to 127.0.0.1, meaning the local machine. If your function host runs in a Docker container, 127.0.0.1 points inside that container, not at Azurite running on your host. Use host.docker.internal in the explicit connection string form instead.
Never publish UseDevelopmentStorage=true to Azure: the Functions host will fail to start. Azure App Settings needs a real storage account connection string, not the Azurite shorthand.

Debugging in VS Code

Required extensions

Two extensions are needed:

Azure Functions (ms-azuretools.vscode-azurefunctions): provides the ${command:azureFunctions.pickProcess} variable that makes F5 work, and the Execute Function Now... command for triggering non-HTTP functions from the editor
C# Dev Kit (ms-dotnettools.csdevkit): the recommended C# extension for new setups. Installs the base C# extension (ms-dotnettools.csharp) automatically, which provides the coreclr debugger needed for attaching to the worker process.

Recommended additions:

Azurite (Azurite.azurite): start and stop Azurite directly from the Command Palette without switching to a terminal
REST Client (humao.rest-client): run .http files against your functions from inside the editor

The F5 workflow

When you press F5 on a Functions project, the following sequence runs:

VS Code executes the build (functions) task from tasks.json (a dotnet build with --no-incremental)
The Azure Functions extension starts func start
func.exe launches the worker process (dotnet.exe)
The extension resolves the worker PID via ${command:azureFunctions.pickProcess}
The coreclr debugger attaches to the worker process
Breakpoints activate

Generated launch.json

Running func init for a dotnet-isolated project generates this configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to .NET Functions",
      "type": "coreclr",
      "request": "attach",
      "processId": "${command:azureFunctions.pickProcess}"
    }
  ]
}

"request": "attach" is not a mistake. The worker process is started by func.exe, not by VS Code, so VS Code cannot launch it. It can only attach to it after the fact. The ${command:azureFunctions.pickProcess} variable is what prompts the process picker if the extension cannot auto-detect the right PID.

tasks.json

The extension generates five tasks. The critical one is the func: host start task at the bottom:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "clean (functions)",
            "command": "dotnet",
            "args": [
                "clean", "${workspaceFolder}/MyProject.csproj",
                "/property:GenerateFullPaths=true",
                "/consoleloggerparameters:NoSummary"
            ],
            "type": "process",
            "problemMatcher": "$msCompile"
        },
        {
            "label": "build (functions)",
            "command": "dotnet",
            "args": [
                "build", "${workspaceFolder}/MyProject.csproj",
                "/property:GenerateFullPaths=true",
                "/consoleloggerparameters:NoSummary"
            ],
            "type": "process",
            "dependsOn": "clean (functions)",
            "group": { "kind": "build", "isDefault": true },
            "problemMatcher": "$msCompile"
        },
        {
            "type": "func",
            "label": "func: host start",
            "command": "host start",
            "options": {
                "cwd": "${workspaceFolder}/bin/Debug/net10.0"
            },
            "isBackground": true,
            "dependsOn": "build (functions)",
            "problemMatcher": "$func-dotnet-isolated-watch"
        }
    ]
}

The func task type points cwd at the compiled output directory because the isolated worker is an executable that runs from there. The problemMatcher is $func-dotnet-isolated-watch (not $func-dotnet-watch, which is for in-process). The dependsOn chain means F5 triggers a build before starting the host.

If you create a project via func init on the CLI instead of through the VS Code extension, you may not get .vscode files automatically. Run Azure Functions: Initialize Project for Use with VS Code from the Command Palette to generate them.

Setting breakpoints and inspecting state

Click the gutter (left of line numbers) to set a breakpoint. When the function is triggered, execution pauses. From there:

Variables panel: all locals and parameters in scope
Hover over any identifier: shows its current value inline
Debug Console: evaluates any C# expression against live state (LINQ works, method calls work)
Call Stack panel: the full call chain from the gRPC dispatcher into your function code

Testing non-HTTP functions from VS Code

Command Palette → Azure Functions: Execute Function Now... → select Local project → pick the function.

This posts to the admin endpoint: POST http://localhost:7071/admin/functions/{FunctionName} with {"input": ""}. For queue triggers, set input to the message body you want to inject.

Common pitfall

Opening a subfolder of your project instead of the folder containing host.json causes F5 to fail without a clear error. The .vscode folder is not found. Always open the project root.

Debugging in Visual Studio 2026

Prerequisites

Visual Studio 2026 (GA since November 2025) is required for .NET 10 development. Visual Studio 2022 cannot target net10.0. Install Visual Studio 2026 from the standard Visual Studio installer.

Install the Azure development workload during setup or add it afterward via the Visual Studio Installer. This adds the Functions project templates and Core Tools integration. Update Core Tools separately when Visual Studio prompts, or through Tools | Options | Projects and Solutions | Azure Functions | Check for Updates.

The F5 workflow

Visual Studio builds the project
Visual Studio launches func.exe (output visible in the terminal pane)
func.exe starts the worker (dotnet.exe) and reports the worker PID back over gRPC
Visual Studio automatically attaches its debugger to the worker dotnet.exe process

No launch.json is needed. Visual Studio handles the two-process attach automatically.

Useful VS-specific features

App Settings dialog: right-click the project → Publish → Hosting → Manage Azure App Service settings. It shows a side-by-side view of local local.settings.json values vs. Azure App Settings, and lets you push individual values to Azure with one click, useful for keeping environments in sync without manually copying strings.
Remote debugging: attach to a deployed function app from Visual Studio. Requires Premium or App Service plan (not Consumption or Flex), Windows OS, and a Debug build. Available for 48 hours before it auto-disables. Use Attach to Process, set the connection type to Microsoft Azure App Services, then select dotnet.exe in the process list.

Known issue

In some Core Tools versions, starting with debugging can take 60 seconds to attach while starting without debugging is instant. Updating Core Tools via Tools | Options | Azure Functions resolves this in most cases.

Debugging in Rider

Plugin requirement

The Azure Toolkit for Rider is not bundled with Rider and is not part of the JetBrains marketplace defaults. Install it from Settings | Plugins | Marketplace, search for "Azure Toolkit for Rider". The current version is v4.6.5 (November 2025), a full rewrite of v3.x. Existing v3.x run configurations are not forward-compatible.

The run configuration trap

When you open a Functions project, Rider generates two run configurations:

.NET Launch Settings Profile: based on launchSettings.json. This does not work for Azure Functions. Ignore it.
Azure Function Host: the correct one. Rider calls func.exe with the right flags internally.

If you see "Broken configuration due to unavailable plugin" after installing or updating to v4.0, delete the old configuration and create a new "Azure Function Host" configuration from scratch via Run | Edit Configurations | + | Azure Function Host.

Debugging workflow

Select the Azure Function Host configuration and press Shift+F9. Rider:

Builds the project
Starts func.exe with --dotnet-isolated-debug
Reads the worker PID from the host's stdout
Attaches the Rider debugger to the worker process

Each [Function] method gets gutter icons: the bug icon starts that function in debug mode, and the play icon opens a .http scratch file with an invocation request ready to send from Rider's built-in HTTP client.

Known bugs

"Azure Functions host did not return isolated worker process id": Rider reads the PID from the host log output. If the logging level in host.json is set above Information, the PID line is suppressed and Rider cannot detect the process. Fix: set "logging": { "logLevel": { "default": "Information" } } in host.json. JetBrains has marked this as wontfix upstream: the PID must come from the host log line.
Slow or failed debugger attach: start without debugging via the Run button, then attach manually through Run | Attach to Process and select the worker dotnet process.
Port configuration: the Azure Function Host run configuration does not read the port from launchSettings.json. Set the port directly in Run | Edit Configurations | Function host arguments. The default 7071 is fine for most setups.

Hot reload and dotnet watch

Hot reload support for Azure Functions isolated worker depends on which tool starts the session:

Start method	What happens on save
Visual Studio F5	True hot reload (Edit and Continue). Most method body changes apply without restart.
`dotnet watch`	Full process restart. All in-memory state is lost.
`func start` (and Rider's Azure Function Host config)	No change detection. Stop and restart manually.
VS Code F5	Full process restart when you stop and re-run.

Visual Studio hot reload

Changes that apply without a restart:

Code changes inside existing method bodies
Adding new methods, properties, or fields to existing types

Changes that require a full restart (rude edits):

Adding a new trigger function (new [Function] attribute)
Changing binding attributes ([QueueTrigger], [BlobTrigger], etc.)
Changing Program.cs startup code
Changes to host.json or local.settings.json
Adding new types or changing method signatures

The binding attribute restriction is the most relevant one for daily Functions development: any time you add a new trigger or modify a binding, you need a full restart.

One gotcha: mixed-mode debugging (the "Enable native code debugging" checkbox in project properties) breaks hot reload. If hot reload stopped working after enabling that option, that's why.

dotnet watch

With Microsoft.Azure.Functions.Worker.Sdk 2.0.0+, dotnet run is supported when Core Tools is installed. dotnet watch wraps dotnet run and restarts the process on file changes:

dotnet watch

This is a full restart, not hot reload. Useful if you want automatic restarts without manually stopping and restarting func start, but in-memory state does not survive between restarts. On Windows, requires the MSI or winget Core Tools installation (not npm).

The --dotnet-isolated-debug flag

func start --dotnet-isolated-debug

This flag starts the worker process, pauses it immediately, and prints:

Azure Functions .NET Worker (PID: 28664) initialized in debug mode. Waiting for debugger to attach...

The process stays paused until you manually attach a debugger. Use it when:

You need to debug Program.cs startup code before any function gets called (the worker pauses before startup completes, so you can attach and step through the entire initialization sequence)
VS Code or Rider is not auto-attaching to the correct process

For typical VS Code or Rider development, you do not need this flag. The IDE extensions handle process detection automatically.

Testing non-HTTP triggers locally

Every locally running Functions host exposes an admin API. Any trigger type can be invoked through it, without waiting for the actual trigger to fire.

The admin endpoint

# Timer trigger (input can be empty)
curl -X POST http://localhost:7071/admin/functions/CleanupFunction \
  -H "Content-Type: application/json" \
  -d '{"input": ""}'

# Queue trigger (input = the queue message body)
curl -X POST http://localhost:7071/admin/functions/OrderProcessor \
  -H "Content-Type: application/json" \
  -d '{"input": "{\"orderId\": \"ord-123\", \"amount\": 99.99}"}'

# Blob trigger
curl -X POST http://localhost:7071/admin/functions/ImageProcessor \
  -H "Content-Type: application/json" \
  -d '{"input": "test-blob-content"}'

The function name in the URL is the string in [Function("...")], not the C# method name.

Simulating real storage events

The admin endpoint is fast for testing, but it bypasses the actual trigger mechanism. For testing the trigger polling behavior, use Azurite directly:

Add a message to an Azurite queue: the queue trigger picks it up on the next poll cycle (default: 2 seconds locally)
Upload a blob to an Azurite container: the blob trigger fires

Azure Storage Explorer (the desktop app) and the Azure Storage VS Code extension both work against Azurite. Point them at http://127.0.0.1:10000 and use the well-known devstoreaccount1 credentials.

.http scratch files

Create requests.http in the project root for quick invocations during development:

### Trigger cleanup manually
POST http://localhost:7071/admin/functions/CleanupFunction
Content-Type: application/json

{"input": ""}

### Test HTTP endpoint
POST http://localhost:7071/api/orders
Content-Type: application/json

{
  "orderId": "ord-123",
  "customerId": "cust-456",
  "amount": 99.99
}

REST Client (VS Code), Rider's built-in HTTP client, and Visual Studio's native .http editor all execute these files with a click.

Productivity tips

Two log streams, two configs

In the isolated worker model, logging is split across two configuration points:

host.json: controls the Functions host logs (trigger polling, execution lifecycle, binding errors)
Worker-side (appsettings.json or Program.cs): controls your ILogger<T> calls

Changes to one do not affect the other. To see your Information-level logs during local development without drowning in host noise:

// host.json
{
  "version": "2.0",
  "logging": {
    "logLevel": {
      "default": "Information",
      "Host.Aggregator": "Trace",
      "Host.Results": "Information"
    }
  }
}

// appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "MyFunctionApp": "Debug"
    }
  }
}

Application Insights drops worker logs by default

If you add Application Insights to a local setup and your ILogger calls stop appearing, this is why: Application Insights registers a default filter rule in the isolated worker model that drops Information and Debug logs. To remove it, update Program.cs:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

// Application Insights registers a default filter rule that drops everything
// below Warning. Remove it to allow Information-level logs through.
builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
{
    LoggerFilterRule? defaultRule = options.Rules.FirstOrDefault(rule =>
        rule.ProviderName
        == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

    if (defaultRule is not null)
    {
        options.Rules.Remove(defaultRule);
    }
});

builder.Build().Run();

If you prefer to avoid touching Program.cs, you can configure Application Insights log levels through appsettings.json instead. Add this file to your project root (set "Copy to Output Directory" to "Copy if newer"):

{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "ApplicationInsights": {
      "LogLevel": { "Default": "Information" }
    }
  }
}

When using FunctionsApplication.CreateBuilder, this file is loaded automatically and the filter removal code above is not needed.

Use APPLICATIONINSIGHTS_CONNECTION_STRING, not the instrumentation key

Microsoft ended instrumentation key ingestion support on March 31, 2025. For any project started after that date, use the connection string setting in local.settings.json:

"APPLICATIONINSIGHTS_CONNECTION_STRING": "InstrumentationKey=...;IngestionEndpoint=https://..."

Do not set both. If both are present, newer SDKs ignore the key.

Override log levels without restarting

Use double-underscore environment variable overrides in local.settings.json:

"AzureFunctionsJobHost__logging__logLevel__default": "Debug"

This overrides host.json log levels without touching the file or restarting func start. Useful for temporarily enabling verbose output to track down a specific issue.

host.json queue settings for faster debugging

{
  "extensions": {
    "queues": {
      "batchSize": 1,
      "visibilityTimeout": "00:00:05",
      "maxDequeueCount": 3
    }
  }
}

batchSize: 1: processes one queue message at a time, making it much easier to follow execution in the logs
visibilityTimeout: "00:00:05": failed messages reappear in 5 seconds instead of the default 10 minutes, so you can iterate on error handling without waiting
maxDequeueCount: 3: messages move to the poison queue after 3 failures (default is 5)

Terminal aliases

# Add to .zshrc / .bashrc
alias fstart='func start'
alias fstartd='func start --dotnet-isolated-debug'
alias fstartv='func start --verbose'

# Start Azurite in background, then start the function host
alias devstart='azurite --silent --location /tmp/azurite & func start'

What's next

You can now run any trigger type locally, attach a debugger to your actual function code, test non-HTTP functions without waiting for real messages, and reproduce storage-related behaviors against Azurite without touching a live Azure subscription.

Part 5 goes deeper into the architecture you've been running locally: the isolated worker model. Why Microsoft created a separate worker process, what you gain over the old in-process model, and what the November 2026 end-of-support deadline means for existing projects.