DEV Community: Martin Oehlert

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.

Beyond HTTP: Timer, Queue, and Blob Triggers

Martin Oehlert — Fri, 20 Feb 2026 06:36:52 +0000

Every .NET team has that one Windows Service nobody wants to touch: the nightly cleanup job, the queue processor, the file watcher duct-taped to a scheduled task. Azure Functions replaces all three with a few lines of C# and a NuGet package.

In Part 2, you built an HTTP-triggered function, the classic request/response pattern. That's the front door. This article opens the rest of the building: the scheduled jobs, the message processors, and the file handlers that run without anyone clicking a button.

Three trigger types beyond HTTP:

Timer triggers: scheduled jobs on a cron expression. Think nightly cleanups, periodic syncs, report generation.
Queue triggers: asynchronous message processing. Decouple your services and handle work at your own pace.
Blob triggers: react to files being created or updated in Azure Storage. Image processing, data imports, log analysis.

All examples use .NET 10 with the isolated worker model and C# 14, same as Part 2. Each trigger gets a real-world scenario, working code, and guidance on when to pick it over the alternatives.

Prerequisites

If you followed Part 2, you already have .NET 10 SDK, Azure Functions Core Tools v4, and VS Code installed. That setup still applies. Head back to that post if you need to get your environment ready.

One tool that becomes essential this time: Azurite. For HTTP triggers it was optional, but timer, queue, and blob triggers all rely on Azure Storage for checkpoint and lease management. Without Azurite running locally, none of these triggers will start. Make sure it is installed and running before you continue.

One thing from Part 2's Program.cs you won't need here: ConfigureFunctionsWebApplication(). That call (and the FrameworkReference to Microsoft.AspNetCore.App) is specific to HTTP triggers with ASP.NET Core integration. For a project with only timer, queue, and blob triggers, your entry point can be as minimal as:

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

You will also need three new NuGet packages, one per trigger type. Each trigger section below shows its specific package, and the Putting It All Together section at the end has the complete .csproj reference with all packages in one place.

Timer Triggers: Scheduled Jobs

What They Are

If you've ever set up a cron job on Linux or a scheduled task on Windows, timer triggers will feel instantly familiar. They're the serverless equivalent: code that runs on a schedule, without you managing the scheduler infrastructure. Think cleanup jobs that purge stale records, nightly report generation, periodic health checks against downstream APIs, cache warming, or syncing data between systems on a regular cadence.

CRON Expression Syntax

Azure Functions uses NCrontab format, and here's the first thing that trips people up: it's a six-field expression, not the standard five-field cron you probably know from Linux. The extra field at the beginning represents seconds.

The format is: {second} {minute} {hour} {day} {month} {day-of-week}

Here are the schedules you'll reach for most often:

Schedule	Expression
Every 5 minutes	`0 /5 * * *`
Every hour	`0 0 * * * *`
Daily at 2 AM UTC	`0 0 2 * * *`
Weekdays at 9 AM	`0 0 9 * * 1-5`
First of every month	`0 0 0 1 * *`

All times are UTC by default. If you need a different timezone, set the WEBSITE_TIME_ZONE app setting to a valid timezone identifier (like Eastern Standard Time on Windows or America/New_York on Linux). Don't skip this if your business logic is timezone-sensitive: "daily at 2 AM" means very different things in UTC versus your local time.

And seriously, remember the six fields. If you paste a five-field expression from Stack Overflow, you'll get a cryptic startup error. The leading 0 for seconds is easy to forget.

Code Sample

Add the timer extension to your project:

<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Timer" Version="4.3.1" />

Here's a timer function that runs a daily cleanup job at 2 AM UTC:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace TriggerDemo;

public class CleanupFunction(ILogger<CleanupFunction> logger)
{
    [Function(nameof(CleanupFunction))]
    public Task Run(
        [TimerTrigger("0 0 2 * * *")] TimerInfo timer)
    {
        logger.LogInformation("Running daily cleanup at {Time}", DateTime.UtcNow);

        if (timer.IsPastDue)
        {
            logger.LogWarning("Timer is running late — a scheduled run was missed");
        }

        logger.LogInformation(
            "Next occurrence: {Next}",
            timer.ScheduleStatus?.Next);

        // Cleanup logic here
        return Task.CompletedTask;
    }
}

The class uses a primary constructor (CleanupFunction(ILogger<CleanupFunction> logger)) to inject the logger directly. No boilerplate field assignments needed. This is the same dependency injection pattern we used with HTTP triggers.

The [Function(nameof(CleanupFunction))] attribute registers the function with the host. Using nameof() instead of a hardcoded string keeps things refactor-safe: rename the class and the function name follows automatically.

The [TimerTrigger("0 0 2 * * *")] attribute is where you specify the CRON expression. This one fires once daily at 2 AM UTC.

The TimerInfo parameter is what the runtime hands you. It exposes two properties you'll actually use: IsPastDue tells you if this execution was delayed (the host was down or restarting when the trigger should have fired), and ScheduleStatus gives you Last, Next, and LastUpdated timestamps so you can log or act on schedule metadata.

Externalizing the Schedule

Hardcoding a CRON expression works for demos, but in real projects you'll want different schedules per environment. Your dev cleanup doesn't need to run at the same cadence as production. Use the %AppSettingName% syntax to pull the schedule from configuration:

[TimerTrigger("%CLEANUP_SCHEDULE%")]

Then define CLEANUP_SCHEDULE in your local.settings.json for local development and in App Settings for each deployed environment. Now you can run every 30 seconds in dev and every 24 hours in production without changing a line of code.

Key Behaviors and Gotchas

Singleton execution. Only one instance of a timer function runs at a time, even when your function app is scaled out to multiple instances. The runtime uses blob leases to coordinate this. You don't need to build your own distributed locking.

UseMonitor. Defaults to true for schedules with intervals of one minute or longer. When enabled, the runtime persists schedule status to blob storage so it can detect missed executions across restarts. That's how IsPastDue works. For sub-minute schedules, it's disabled automatically.

RunOnStartup. Setting this to true fires the function immediately whenever the host starts. Sounds convenient for testing, but it's a trap in production. Every deployment, every scale-out event, every platform restart triggers your function. Leave it off.

No automatic retry by default. If your timer function throws an exception, the runtime won't retry it. It simply waits for the next scheduled occurrence. If your cleanup job fails at 2 AM, it won't run again until 2 AM tomorrow. For critical work, add a retry policy to the method: [FixedDelayRetry(5, "00:00:10")] retries up to five times with a ten-second delay between attempts. One caveat: timer retries don't survive instance failures. If the host crashes mid-retry sequence, the count is lost and won't resume on a new instance.

Testing Timer Functions Locally

You don't want to wait until 2 AM to test your function. During local development, you can trigger any timer function on demand by POSTing to the admin endpoint:

curl -X POST http://localhost:7071/admin/functions/CleanupFunction \
  -H "Content-Type: application/json" \
  -d '{"input": null}'

This returns a 202 Accepted and fires the function immediately, regardless of the CRON schedule. It's a lifesaver, especially for schedules like "first of every month" where waiting for the natural trigger isn't exactly practical. The same admin endpoint works for any function type, but you'll use it most with timers.

Queue Triggers: Async Message Processing

Not everything needs to happen right now. When a user places an order, they don't need to wait while you generate an invoice, send a confirmation email, and update your analytics dashboard. Queue triggers let you drop a message onto an Azure Storage Queue and process it asynchronously, decoupling the thing that creates work from the thing that does work.

This is the backbone of reliable distributed systems. Producers and consumers scale independently, failures don't cascade, and traffic spikes get absorbed by the queue instead of hammering your downstream services.

Common use cases: order processing, sending emails, image or document processing, fan-out patterns where one event kicks off multiple downstream tasks.

Code Sample: Order Processor

Add the queue storage extension to your project:

<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues" Version="5.5.3" />

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace TriggerDemo;

public record OrderMessage(string OrderId, string CustomerId, decimal Amount);

public class OrderProcessor(ILogger<OrderProcessor> logger)
{
    [Function(nameof(OrderProcessor))]
    public async Task Run(
        [QueueTrigger("orders", Connection = "AzureWebJobsStorage")]
        OrderMessage order)
    {
        logger.LogInformation(
            "Processing order {OrderId} for {CustomerId}: {Amount:C}",
            order.OrderId, order.CustomerId, order.Amount);

        // Process order...
    }
}

The OrderMessage record defines the shape of your queue message. Records are perfect here: they're immutable, concise, and the positional syntax gives you a clean one-liner. The runtime deserializes the JSON message body straight into this type automatically.

QueueTrigger("orders") tells the runtime to watch the queue named orders. Every time a message lands there, your function fires.

The Connection parameter isn't the connection string itself; it's the name of the setting that holds the connection string. Locally, that's a key in local.settings.json. In Azure, it's an app setting or a Key Vault reference.

The runtime handles auto-deserialization from JSON to your POCO or record. But you're not limited to custom types; you can also bind to string (raw message content), byte[], BinaryData, or QueueMessage if you need access to metadata like dequeue count or insertion time.

Queue Output Binding

Often you'll want to chain processing steps: read from one queue, do some work, and drop a message onto another queue. Output bindings handle this:

[Function(nameof(OrderProcessor))]
[QueueOutput("notifications", Connection = "AzureWebJobsStorage")]
public string Run(
    [QueueTrigger("orders", Connection = "AzureWebJobsStorage")]
    OrderMessage order)
{
    logger.LogInformation("Processing order {OrderId}", order.OrderId);
    return $"Order {order.OrderId} processed for {order.CustomerId}";
}

The pattern here is simple: the function's return value becomes the output message. The QueueOutput attribute on the method tells the runtime where to send it. Whatever string you return gets written to the notifications queue. Each function does one job and passes work to the next stage.

You'll notice this version is synchronous: public string Run(...) instead of async Task Run(...). When the only job is to transform input and return an output message, there's no async work involved. If you need to do async work before emitting the output message, change the return type to Task<string> and await normally inside.

Poison Queue Handling

What happens when processing fails? The runtime retries. And retries again. By default, if a message fails 5 times (the maxDequeueCount), it gets moved to a special queue named {queue-name}-poison (in our case, orders-poison).

You can tune this in host.json:

{
  "extensions": {
    "queues": {
      "maxDequeueCount": 3
    }
  }
}

Poison queues are your safety net, but only if you're watching them. A message sitting in a poison queue means something broke and data isn't being processed. Set up alerts on the poison queue message count. Azure Monitor can do this, or you can write a simple timer trigger (see what we did there?) that checks the count and pings your team in Slack or Teams. Don't let poison messages pile up silently.

Scaling and Concurrency

The Functions runtime continuously polls the queue and scales out based on queue length. More messages means more instances; you don't configure this, it just happens.

What you can configure in host.json:

batchSize (default 16): how many messages each instance grabs at once
newBatchThreshold (default batchSize / 2 on Consumption plan, scaled by vCPU count on App Service and Premium plans): when to fetch the next batch
visibilityTimeout: how long a message stays invisible to other consumers while being processed

One critical thing to understand: there are no ordering guarantees. Messages may be processed out of order, and with at-least-once delivery semantics, the same message could be processed more than once. This means your processing logic must be idempotent, meaning safe to run twice with the same input without creating duplicate side effects. Use an idempotency key (like the OrderId above) and check whether you've already processed a message before doing the work. Skip this, and you'll eventually process the same order twice on a busy day.

Testing Locally

Start Azurite to get a local storage emulator running (you should already have it from the timer trigger section). Your function will connect using the UseDevelopmentStorage=true connection string.

To put test messages on the queue, you've got a few options:

Azure Storage Explorer: right-click the queue and add a message manually. Great for quick one-offs.
Azure CLI: az storage message put --queue-name orders --content '{"OrderId":"123","CustomerId":"C1","Amount":49.99}' with the --connection-string flag pointing at Azurite.
An HTTP trigger: create a simple function that accepts an order via HTTP and writes it to the queue. This is genuinely useful beyond testing; it's often how messages end up on queues in production too.

Whichever approach you choose, watch the terminal output from func start; you'll see your function pick up the message within seconds.

Blob Triggers: File Processing

Files show up and need processing. A customer uploads an invoice PDF, a partner drops a data feed into storage, a mobile app pushes photos for moderation. You could poll for new files on a timer, but that's wasteful and slow. Blob triggers let your function react to files being created or updated in Azure Blob Storage. The moment a blob lands, your code runs.

This is the pattern behind image processing pipelines (generate thumbnails on upload), file format conversion (CSV lands, gets parsed into database rows), log ingestion (application dumps a log file, your function indexes it), data imports, and virus scanning workflows. Anywhere you'd previously have a Windows Service watching a folder or a scheduled job sweeping a directory, blob triggers are the serverless replacement.

Blob Trigger vs Input Binding

This distinction confuses people coming from a pure HTTP background, but it matters. Azure provides two blob-related attributes, and they solve different problems:

	Blob Trigger	Blob Input Binding
Purpose	Starts function execution	Reads data during execution
When it fires	New or modified blob detected	After another trigger fires
Attribute	`[BlobTrigger]`	`[BlobInput]`
Typical use case	React to file uploads	Read a known config or template file

A blob trigger is the event source; it causes your function to run. A blob input binding is a convenience for reading a blob inside a function that was triggered by something else. For example, you might have a queue trigger that processes orders, and that function needs to read a pricing template stored as a blob. The queue message triggers execution; the blob input binding reads the template. Two different roles, two different attributes.

Don't use a blob trigger when you already know which blob you need. And don't use an input binding when you need to react to new files arriving. That's the trigger's job.

Code Sample: Image Processor

Add the blob storage extension to your project:

<PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs" Version="6.8.0" />

Here's a function that watches an uploads container and generates a thumbnail every time an image arrives:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace TriggerDemo;

public class ImageProcessor(ILogger<ImageProcessor> logger)
{
    [Function(nameof(ImageProcessor))]
    [BlobOutput("thumbnails/{name}", Connection = "AzureWebJobsStorage")]
    public byte[] Run(
        [BlobTrigger("uploads/{name}", Connection = "AzureWebJobsStorage")]
        byte[] imageData,
        string name)
    {
        logger.LogInformation("Processing uploaded image: {Name} ({Size} bytes)",
            name, imageData.Length);

        // Generate thumbnail...
        byte[] thumbnailBytes = GenerateThumbnail(imageData);
        return thumbnailBytes;
    }

    private static byte[] GenerateThumbnail(byte[] imageData)
    {
        // Thumbnail generation logic
        return imageData; // placeholder
    }
}

The [BlobTrigger("uploads/{name}")] attribute is doing two things at once. First, it tells the runtime to watch the uploads container for new or modified blobs. Second, the {name} path pattern is a binding expression; it captures the blob's filename and makes it available as a method parameter. When someone uploads uploads/profile-photo.jpg, the name parameter receives "profile-photo.jpg". This is how you know which file triggered your function.

The Connection parameter works the same way it does with queue triggers; it's the name of the app setting that holds your storage connection string, not the connection string itself. AzureWebJobsStorage points to Azurite during local development.

The method parameter byte[] imageData receives the entire blob content as a byte array. This is the simplest binding type and works well when your files fit comfortably in memory. But you're not limited to byte[]; the runtime supports several binding types depending on your needs:

Stream: best for large files where you want to process data without loading everything into memory at once
BinaryData: a modern Azure SDK type that wraps binary content with convenient conversion methods
string: for text-based blobs like CSV, JSON, or log files
byte[]: when you need the raw bytes (image processing, binary formats)
BlobClient: gives you the full Azure Storage SDK client, useful when you need blob metadata, properties, or want to copy/move the blob rather than just read it

The [BlobOutput("thumbnails/{name}")] attribute on the method tells the runtime to write the return value to a different container. Notice the {name} pattern appears here too, reusing the same captured filename, so uploads/profile-photo.jpg produces thumbnails/profile-photo.jpg. The function's return type matches the output: return a byte[], and that's what gets written. This input-container-to-output-container pattern is the standard approach for blob processing, and the separation is deliberate (more on why in the gotchas section).

Path Patterns and Filtering

The path pattern in [BlobTrigger] is more powerful than a simple container name. You can use it to filter which blobs trigger your function and to extract structured metadata from your blob paths.

Filter by file extension to react only to specific file types:

[BlobTrigger("uploads/{name}.csv", Connection = "AzureWebJobsStorage")]

This function only fires for CSV files. Upload a .csv and the function runs; upload a .png and nothing happens. The name parameter receives just the filename without the extension. Upload report-2026.csv and name is "report-2026".

Extract path segments when your storage uses a meaningful directory structure:

[BlobTrigger("uploads/{category}/{filename}.{ext}", Connection = "AzureWebJobsStorage")]
public void Run(byte[] data, string category, string filename, string ext)

Now each segment of the path binds to its own parameter. A blob at uploads/invoices/INV-2026-001.pdf gives you category = "invoices", filename = "INV-2026-001", and ext = "pdf". You can route processing logic based on the category, log the extension, or construct output paths dynamically.

Design your container directory structure with these patterns in mind. A flat dump of files into a single container works, but a structured layout like uploads/{department}/{year}/{filename} gives you filtering and metadata for free.

Key Gotchas

Infinite loops will ruin your day. If your function triggers on blobs in the uploads container and writes output back to the same uploads container, the output blob triggers the function again. Which writes another blob. Which triggers again. This loop runs until you notice it, your storage bill spikes, or you hit a concurrency limit. Always use separate containers for input and output. The code sample above reads from uploads and writes to thumbnails. That separation is intentional and non-negotiable. If you remember one thing from this section, make it this.

Latency is worse than you'd expect. The default blob trigger uses a polling mechanism that scans for changes. On the Consumption plan, this can take up to 10 minutes to detect a new blob. That's not a typo. Minutes, not seconds. If near-instant detection matters for your scenario (and it usually does), use the Event Grid-based blob trigger instead. It subscribes to Azure Event Grid notifications and fires within seconds of blob creation. For anything going to production, Event Grid is the recommended approach. The polling-based trigger is fine for development and low-urgency workloads, but don't ship it to production assuming instant response times. Locally with Azurite, detection typically takes under 60 seconds.

Blob receipts track what's been processed. The runtime stores receipts in the azure-webjobs-hosts container to avoid reprocessing the same blob. If processing fails 5 times, the blob's receipt is marked as poisoned and the runtime stops retrying. Unlike queue triggers, there's no separate "poison container"; the receipt just gets flagged. You'll need to monitor your logs to catch these failures, because nothing moves visibly. If you need to reprocess a failed blob, delete its receipt from azure-webjobs-hosts and the runtime will pick it up again.

Cold starts compound the latency problem. On the Consumption plan, if your function app has been idle, it may need to cold-start before it can even begin polling for blobs. Combined with the polling interval, you could be looking at significant delays. Two mitigations: use a timer trigger as a keep-alive (a function that runs every few minutes just to keep the host warm), or switch to an App Service Plan with Always On enabled. The Flex Consumption plan also helps here with its pre-warmed instance pool.

Choosing the Right Trigger

You've now seen three trigger types in action: timer, queue, and blob. Each one solves a fundamentally different problem, and picking the right one usually comes down to a single question: what event starts the work?

If the answer is "a clock" (something needs to happen at a specific time or on a recurring interval), that's a timer trigger. If the answer is "a message" (another service is telling you there's work to do), that's a queue trigger. If the answer is "a file showed up" (someone uploaded something, or an external system dropped a CSV into storage), that's a blob trigger.

In practice, the choice is usually obvious once you frame it that way. But here's a quick reference for common scenarios:

Scenario	Trigger	Why
Run at 2 AM daily	Timer	Schedule-based, no external event needed
Process uploaded files	Blob	Reacts to blob storage events
Background task after user action	Queue	Decouple request from processing
Process orders asynchronously	Queue	Reliable message processing with retries
Health check every 5 minutes	Timer	Periodic polling
ETL pipeline from file drops	Blob	File arrival triggers processing

flowchart TD
    A([What starts the work?]) --> B{Clock or schedule?}
    B -->|Yes| Timer[⏰ Timer Trigger]
    B -->|No| C{Message from another service?}
    C -->|Yes| Q{Need ordering or pub/sub?}
    Q -->|No| Queue[📨 Queue Trigger\nStorage Queue]
    Q -->|Yes| SB[🚌 Service Bus Trigger]
    C -->|No| D{File arrived in storage?}
    D -->|Yes| Blob[📁 Blob Trigger]
    D -->|No| HTTP([HTTP Trigger\nor other event])

Timer for time, queue for commands, blob for files. If you're unsure, ask yourself whether the trigger is driven by the clock, by another service's intent, or by data arriving in storage. The answer almost always maps cleanly to one of the three.

And in many real-world systems, you'll combine them. A timer trigger runs nightly to check for missing invoices, drops a message per missing invoice onto a queue, and the queue trigger processes each one. Or a blob trigger picks up an uploaded CSV, validates it, and enqueues individual rows for downstream processing. These triggers compose naturally. That's by design.

When to Consider Service Bus Over Storage Queues

Everything in this article uses Azure Storage Queues; they're simple, cheap, and included with any storage account you're already using. For most use cases, they're the right starting point.

But Storage Queues have limits, and you'll hit them eventually. Here's when to look at Azure Service Bus instead:

You need guaranteed ordering. Storage Queues offer no ordering guarantees at all. Service Bus sessions give you FIFO processing for messages that share a session ID, which is essential for scenarios where event order matters, like processing state changes for the same entity.
You need pub/sub. Storage Queues are point-to-point: one message, one consumer. If the same event needs to reach multiple subscribers (say, an order placed event triggers inventory, billing, and notifications), Service Bus topics and subscriptions let multiple consumers each get their own copy.
Your messages exceed 64 KB. That's the Storage Queue message size limit. Service Bus supports messages up to 256 KB on the Standard tier and 100 MB on Premium. If you're passing around documents or large payloads, Storage Queues won't cut it.
You need dead-letter queues with inspection. Storage Queues have the poison queue mechanism we covered earlier, but Service Bus dead-letter queues are richer; you can peek messages, inspect failure reasons, and resubmit without custom tooling.
You need duplicate detection or transactions. Service Bus can automatically detect and discard duplicate messages within a configurable window, and it supports transactions that span multiple queues or topics. Storage Queues have neither.

The rule of thumb: start with Storage Queues. Upgrade to Service Bus when you hit a specific limitation. Don't pay the complexity and cost premium upfront "just in case." Storage Queues handle the vast majority of message processing scenarios, and migrating later is not painful. Your function code barely changes. You swap QueueTrigger for ServiceBusTrigger, update the connection string, and adjust the NuGet package. The processing logic inside stays the same.

If you're starting a new project and genuinely aren't sure, go with Storage Queues. You'll know when you've outgrown them. It'll be the moment you need ordering, pub/sub, or messages bigger than 64 KB. Until then, keep it simple.

Testing All Triggers Locally with Azurite

You've seen the individual trigger sections mention Azurite in passing. Let's talk about why it's required and how to set up a smooth local development workflow for all three trigger types at once.

Timer, queue, and blob triggers all depend on Azure Storage behind the scenes, even if your function doesn't explicitly use queues or blobs. Timer triggers store checkpoint data in blob storage so the runtime knows when the last execution happened (that's how IsPastDue works). Queue triggers obviously need a queue service. Blob triggers use blob storage for both the trigger source and internal bookkeeping through blob receipts. Without a storage account, none of these triggers can even start.

Azurite is Microsoft's official local storage emulator. It gives you blob, queue, and table services running on your machine. No Azure subscription needed, no network latency, no cost. You connect to it with a well-known connection string, and your functions behave exactly as they would against real Azure Storage.

Configuration

Your local.settings.json needs exactly two settings to make everything work:

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

UseDevelopmentStorage=true is a shorthand connection string that the Azure SDK recognizes. It tells the runtime to connect to Azurite's default endpoints on localhost: port 10000 for blobs, 10001 for queues, and 10002 for tables. No keys, no account names, no URLs to configure.

Starting Azurite

Open a terminal and run:

npx azurite --silent --location /tmp/azurite

The --silent flag suppresses the per-request logging that clutters your terminal (you've got enough output from func start). The --location flag tells Azurite where to persist data on disk. Use /tmp/azurite for throwaway test data, or a project-local folder if you want data to survive reboots. Azurite will create the folder if it doesn't exist.

Leave this running in its own terminal window. Then, in a second terminal, start your function app:

func start

The host will connect to Azurite, create its internal containers (azure-webjobs-hosts for checkpoints, etc.), and register all three trigger types. If Azurite isn't running, you'll see connection-refused errors and the host will fail to start, so always start Azurite first.

A Practical Testing Workflow

Once both Azurite and the function host are running, here's how to exercise all three triggers in a single session:

Timer triggers are the easiest. POST to the admin endpoint:

curl -X POST http://localhost:7071/admin/functions/CleanupFunction \
  -H "Content-Type: application/json" \
  -d '{"input": null}'

You'll get a 202 Accepted and see the function execute immediately in the terminal output. No waiting for the CRON schedule.

Queue triggers need a message on the queue. Use Azure Storage Explorer, the Azure CLI, or a quick curl to push a JSON message:

az storage message put \
  --queue-name orders \
  --content '{"OrderId":"ORD-001","CustomerId":"C42","Amount":129.99}' \
  --connection-string "UseDevelopmentStorage=true"

Your OrderProcessor function will pick it up within seconds.

Blob triggers fire when you upload a file to the watched container. Drop a test file in using the CLI:

az storage blob upload \
  --container-name uploads \
  --name test-image.png \
  --file ./test-image.png \
  --connection-string "UseDevelopmentStorage=true"

Detection can take up to 60 seconds locally given the polling-based mechanism. If your function doesn't fire immediately, give it a minute before assuming something is wrong. For production, you'd use Event Grid for near-instant detection, but locally the default polling works fine.

The admin endpoint (POST http://localhost:7071/admin/functions/{FunctionName} with {"input": null}) works for all function types, not just timers. It's your universal "just run this thing right now" button during development.

Putting It All Together

If you've been following along, you already have the individual NuGet packages installed. Here's the complete .csproj <ItemGroup> with everything you need for HTTP, timer, queue, and blob triggers in a single project:

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="2.51.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Timer" Version="4.3.1" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues" Version="5.5.3" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs" Version="6.8.0" />
</ItemGroup>

The first three packages are the foundation: the worker runtime, the SDK tooling, and the HTTP extension you set up in Part 2. The last three are one extension per trigger type. That's the pattern: each trigger type ships as its own NuGet package. You only install what you use, and you can add triggers incrementally as your project grows. Starting with just timers? Leave out the queue and blob packages. Adding blob processing next sprint? Drop in the one-liner and you're ready.

The extensions share the Microsoft.Azure.Functions.Worker.Extensions.* naming convention, which makes them easy to discover. If you find yourself searching for a new trigger type down the road (Service Bus, Cosmos DB, Event Grid), it'll follow the same Extensions.{ServiceName} pattern.

What's Next

Three more trigger types are now in your toolkit. Timer triggers use six-field CRON expressions and run as singletons even when scaled out; if the host was down when a run was due, IsPastDue tells you so. Queue triggers give you at-least-once delivery with automatic retries and a poison queue for messages that keep failing. Blob triggers fire on file arrival, not a polling loop; separate input and output containers are non-negotiable.

A few principles that cut across all three:

Keep functions focused. One function, one job. Chain them with output bindings rather than cramming everything into a single method.
Make processing idempotent. Messages can be delivered more than once, timer functions can fire late, blob triggers can re-detect files. Design for "safe to run twice" from day one.
Use separate containers for blob I/O. Writing output to the same container you trigger on creates an infinite loop. Always read from one container and write to another.
Test locally with Azurite. Every trigger type in this article works without an Azure subscription. There's no excuse for deploying untested functions.
Use [LoggerMessage] for production logging. The logger.LogInformation(...) calls in this article are intentionally straightforward, but they box value types (decimal, int, DateTime) on every invocation, even when that log level is disabled. Projects with recommended analyzer settings will flag this as CA1873. The fix is the [LoggerMessage] source generation attribute, which creates strongly-typed log methods at compile time and eliminates the boxing:

[LoggerMessage(Level = LogLevel.Information, Message = "Processing order {OrderId}: {Amount:C}")]
private partial void LogOrderProcessing(string orderId, decimal amount);

This is a performance and code quality concern, not a correctness issue; the inline calls in this article work fine for getting started.

All the code samples from this article are available in the sample repository on GitHub.

Next in the series: Part 4 (Local Development Setup: Tools, Debugging, and Hot Reload) will take your local workflow to the next level. We'll cover debugging with breakpoints, hot reload for faster iteration, and the tooling that makes Azure Functions development feel as smooth as working on a regular ASP.NET Core app.

Your First Azure Function: HTTP Triggers Step-by-Step

Martin Oehlert — Fri, 13 Feb 2026 07:23:29 +0000

Theory doesn't ship features. You learned the why in Part 1—when serverless makes sense, the economics, how it compares to App Service and Container Apps. Now let's build something.

In this second part of the Azure Functions for .NET Developers series, we'll create a project from scratch, understand every line of generated code, and build three HTTP trigger patterns that cover most real-world API scenarios. By the end, you'll have a working HTTP API running locally on your machine. No Azure subscription required.

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

Prerequisites

You need four tools installed before we start. Here's what to check and where to get them:

Tool	Verify	Expected
.NET 10 SDK	`dotnet --version`	10.x
Azure Functions Core Tools	`func --version`	4.x
VS Code + Azure Functions extension	—	Latest
Azurite	`npx azurite --version`	Any

.NET 10 SDK is required to build and run our function app. It's an LTS release, supported through November 2028. Grab it from dot.net/download if you don't have it.

Azure Functions Core Tools v4 lets you create, run, and debug functions locally. Install via npm, Homebrew, or Chocolatey:

# npm (any OS)
npm install -g azure-functions-core-tools@4

# Homebrew (macOS)
brew tap azure/functions
brew install azure-functions-core-tools@4

# Chocolatey (Windows)
choco install azure-functions-core-tools-4

VS Code with the Azure Functions extension gives you project templates, debugging, and deployment in one place. Visual Studio and Rider work too—use whatever you're comfortable with. The CLI commands in this article work regardless of editor.

Azurite emulates Azure Storage locally. The Functions runtime needs a storage connection even for HTTP triggers (it uses storage internally for features like function key management and, in production, for coordinating across instances). Install it globally or run it on demand:

# Install globally
npm install -g azurite

# Or run on demand without installing
npx azurite

If the verification commands all return version numbers and you have VS Code with the Azure Functions extension installed, you're ready.

Creating Your First Project

With your tools in place, open a terminal and scaffold a new function app:

func init HttpTriggerDemo --worker-runtime dotnet-isolated --target-framework net10.0
cd HttpTriggerDemo
func new --template "HTTP trigger" --name Hello

The first command creates the project. --worker-runtime dotnet-isolated selects the isolated worker model (the modern default—we'll explain what "isolated" means in Part 5). --target-framework net10.0 targets .NET 10.

Once inside the project directory, func new adds an HTTP-triggered function called Hello from a built-in template.

Your project now looks like this:

HttpTriggerDemo/
├── Hello.cs              # Your function code
├── Program.cs            # Application entry point
├── HttpTriggerDemo.csproj # Project file
├── host.json             # Runtime configuration
└── local.settings.json   # Local environment variables

The Project File

Open HttpTriggerDemo.csproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="2.51.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
  </ItemGroup>
</Project>

A few things to note:

OutputType: Exe — the isolated worker model runs as a standalone executable, not a class library loaded into the Functions host. This is what gives you full control over the process.
FrameworkReference: Microsoft.AspNetCore.App — brings in ASP.NET Core types like HttpRequest and IActionResult. Without this, you'd use the lower-level HttpRequestData API.
Extensions.Http.AspNetCore — the bridge that maps ASP.NET Core's HTTP abstractions to the Functions runtime. This is what makes the developer experience feel like writing a regular web API.
ImplicitUsings: enable — the compiler automatically includes common using statements (System, System.Collections.Generic, System.Linq, System.Threading.Tasks, and others). That's why our code files don't start with a block of using directives.
Nullable: enable — turns on nullable reference types. The compiler warns you when code might dereference null without checking. You'll see this in action when we read query string values—req.Query["name"] returns string?, not string.

The Entry Point

Program.cs is minimal:

using Microsoft.Azure.Functions.Worker.Builder;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

ConfigureFunctionsWebApplication() is the key line. It enables ASP.NET Core integration—without it, you'd need to use HttpRequestData and HttpResponseData instead of the familiar HttpRequest and IActionResult. For HTTP-triggered functions, this is almost always what you want.

FunctionsApplication.CreateBuilder(args) is a convenience factory introduced in Worker SDK 2.0. It returns a pre-configured IHostApplicationBuilder with Functions defaults already wired up—logging, JSON serializer options, and middleware. The key using to remember is Microsoft.Azure.Functions.Worker.Builder, which brings the factory method into scope. You may also see an older pattern that starts with new HostBuilder() and calls .ConfigureFunctionsWorkerDefaults()—it still works, but requires more manual setup (for example, explicit ConfigureAppConfiguration() calls to load appsettings.json). func init scaffolds FunctionsApplication.CreateBuilder by default, so stick with it for new projects.

This is also where you'd register services for dependency injection, add middleware, or configure logging. We'll keep it simple for now.

Understanding the Generated Code

With the project structure in place, let's look at the function itself. The func new command created a file called Hello.cs with a complete working function. Before we run it, let's understand what each part does. Open Hello.cs:

public class Hello(ILogger<Hello> logger)
{
    [Function("Hello")]
    public IActionResult Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req)
    {
        logger.LogInformation("C# HTTP trigger function processed a request.");
        return new OkObjectResult("Welcome to Azure Functions!");
    }
}

Let's break this apart.

public class Hello(ILogger<Hello> logger) uses a C# 12 primary constructor. The ILogger<Hello> parameter is injected by the dependency injection container automatically—no need to write a separate constructor or field assignment. The logger is available throughout the class.

[Function("Hello")] registers this method with the Functions runtime. The string "Hello" becomes the function's name and appears in the URL path: http://localhost:7071/api/Hello. If you rename the class but keep the attribute string the same, the URL stays the same.

[HttpTrigger(AuthorizationLevel.Function, "get", "post")] is where the behavior is defined:

AuthorizationLevel.Function means callers need a function-specific API key to invoke this endpoint. Other options are Anonymous (no key required) and Admin (requires the master host key). When running locally, authorization is bypassed regardless of the level you set.
"get", "post" lists the allowed HTTP methods. Requests using other methods receive a 405 Method Not Allowed.

HttpRequest req is the full ASP.NET Core request object. Query strings, headers, body, route values—it's all there. If you've written ASP.NET Core controllers or minimal APIs, this is the same type.

IActionResult is the return type. OkObjectResult maps to a 200 response. The runtime serializes the object to JSON (or returns it as plain text for strings) and sends it back to the caller. All the familiar result types work: BadRequestResult, NotFoundResult, CreatedResult, and so on.

Run It

Before we modify anything, let's see this function in action. Start Azurite in a separate terminal (or in the background):

npx azurite --silent --location /tmp/azurite &

Then start the Functions runtime from your project directory:

func start

You should see output listing your function's URL:

Functions:

        Hello: [GET,POST] http://localhost:7071/api/Hello

Test it in another terminal:

curl http://localhost:7071/api/Hello
# → Welcome to Azure Functions!

That's a working HTTP endpoint, running locally, no Azure subscription needed. Keep func start running—we'll build on this function next.

HTTP Trigger Deep Dive

With a running function under your belt, let's build three patterns that cover the majority of real-world HTTP function scenarios. After each change, stop func start with Ctrl+C and restart it to pick up the new code.

Pattern 1: GET with Query String

The simplest pattern—read a value from the URL and return a response:

public class HelloFunction(ILogger<HelloFunction> logger)
{
    [Function("Hello")]
    public IActionResult Run(
        [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
    {
        logger.LogInformation("Hello function triggered");

        string? name = req.Query["name"];
        return new OkObjectResult($"Hello, {name ?? "world"}!");
    }
}

req.Query["name"] reads the name parameter from the query string. If it's missing, the value is null, so we fall back to "world" with the null-coalescing operator. Note the string? — the query collection returns a nullable type, and with <Nullable>enable</Nullable> in the project file, the compiler enforces this.

Test it:

curl "http://localhost:7071/api/Hello?name=Azure"
# → Hello, Azure!

curl "http://localhost:7071/api/Hello"
# → Hello, world!

This pattern works well for simple lookups—search queries, filtering lists, or any GET request where the parameters are short and cacheable.

Pattern 2: POST with JSON Body

For creating or updating resources, you'll typically accept a JSON request body. C# records and ASP.NET Core model binding make this clean:

using FromBodyAttribute = Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute;

public record CreateOrderRequest(string ProductId, int Quantity);

public class OrderFunction(ILogger<OrderFunction> logger)
{
    [Function("CreateOrder")]
    public IActionResult CreateOrder(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "orders")] HttpRequest req,
        [FromBody] CreateOrderRequest order)
    {
        logger.LogInformation("Order for {ProductId} x{Quantity}", order.ProductId, order.Quantity);
        return new CreatedResult($"/orders/{Guid.NewGuid()}", order);
    }
}

Several things happening here:

record CreateOrderRequest defines an immutable data type. Records are ideal for request and response DTOs—they give you value equality, a clean ToString(), and immutability out of the box. No need to write a class with properties and a constructor.

[FromBody] CreateOrderRequest order tells the ASP.NET Core model binder to deserialize the JSON request body into a CreateOrderRequest instance. If the JSON doesn't match (missing required fields, wrong types), the runtime returns a 400 Bad Request automatically. One gotcha: with ASP.NET Core integration enabled, FromBody exists in two namespaces—Microsoft.Azure.Functions.Worker.Http and Microsoft.AspNetCore.Mvc. You need the Functions Worker version. The using alias at the top of the file resolves the ambiguity so you can use [FromBody] without a fully qualified name.

Route = "orders" overrides the default route. Without it, the URL would be /api/CreateOrder (derived from the function name). With it, the URL becomes /api/orders—cleaner and more RESTful.

CreatedResult returns HTTP 201 with a Location header pointing to the new resource. Standard REST semantics.

Test it:

curl -X POST http://localhost:7071/api/orders \
  -H "Content-Type: application/json" \
  -d '{"productId":"SKU-001","quantity":3}'
# → {"productId":"SKU-001","quantity":3}
# (with 201 status and Location header)

The Content-Type: application/json header is required. Without it, model binding won't kick in and you'll get a deserialization error.

Pattern 3: Route Parameters

For resource-oriented APIs, you'll want parameters embedded in the URL path rather than the query string:

public class ProductFunction(ILogger<ProductFunction> logger)
{
    [Function("GetProduct")]
    public IActionResult GetProduct(
        [HttpTrigger(AuthorizationLevel.Function, "get",
            Route = "products/{category:alpha}/{id:int?}")] HttpRequest req,
        string category, int? id)
    {
        logger.LogInformation("Looking up {Category}, id={Id}", category, id);
        return new OkObjectResult(new { category, id });
    }
}

Route parameters are defined in curly braces inside the Route string and captured as method parameters matched by name. The runtime extracts category and id from the URL and passes them directly to your method.

Route constraints validate parameters before your code runs:

Constraint	Meaning	Example
`:alpha`	Letters only	`electronics` matches, `123` doesn't
`:int`	Integer	`42` matches, `abc` doesn't
`:int?`	Optional integer	Parameter can be omitted
`:guid`	GUID format	`{id:guid}`
`:length(5)`	Exact string length	`{code:length(5)}`
`:min(1)`	Minimum integer value	`{page:min(1)}`

If a constraint fails, the runtime returns a 404—your function never executes.

Test it:

curl http://localhost:7071/api/products/electronics/42
# → {"category":"electronics","id":42}

curl http://localhost:7071/api/products/electronics
# → {"category":"electronics","id":null}

curl http://localhost:7071/api/products/123/42
# → 404 (constraint :alpha rejects "123")

You now have three working patterns that cover most real-world HTTP function scenarios.

Running and Testing Locally

Restart func start now that all three functions are in place. You should see all of them listed:

Azure Functions Core Tools
Core Tools Version: 4.6.0

Functions:

        CreateOrder: [POST] http://localhost:7071/api/orders

        GetProduct: [GET] http://localhost:7071/api/products/{category:alpha}/{id:int?}

        Hello: [GET] http://localhost:7071/api/Hello

For quick reference, here are all three test commands together:

# Pattern 1: GET with query string
curl "http://localhost:7071/api/Hello?name=Azure"

# Pattern 2: POST with JSON body
curl -X POST http://localhost:7071/api/orders \
  -H "Content-Type: application/json" \
  -d '{"productId":"SKU-001","quantity":3}'

# Pattern 3: Route parameters
curl http://localhost:7071/api/products/electronics/42

You can also use Postman, the REST Client extension for VS Code, or HTTPie—whatever fits your workflow.

A note on authorization: when running locally, AuthorizationLevel.Function is bypassed. You don't need to pass a function key. This makes local development frictionless. Once deployed, clients will need to include the key as a query parameter (?code=<key>) or in the x-functions-key header.

Troubleshooting

If things don't work on the first try, check these common issues:

"Can't determine project language" or "No job functions found"

The .csproj file is missing required settings. Verify it targets net10.0, has <AzureFunctionsVersion>v4</AzureFunctionsVersion>, and includes the Worker SDK packages. Run dotnet build separately to check for compilation errors.

Port 7071 already in use

Another Functions host (or another process) is using the default port. Either kill it or start on a different port:

func start --port 7072

"Value cannot be null: provider" or storage connection errors

Azurite isn't running. The Functions runtime needs a storage emulator even for HTTP triggers. Start Azurite, or verify that local.settings.json contains:

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

UseDevelopmentStorage=true tells the SDK to connect to Azurite on its default ports.

JSON deserialization errors on POST requests

Two common causes: missing the Content-Type: application/json header, or property name mismatches between your JSON and your C# record. By default, the serializer is case-insensitive, so productId and ProductId both work. But the property names must exist on the target type.

"The listener for function X was unable to start"

Usually a runtime version mismatch. Confirm func --version returns 4.x and your .csproj has <AzureFunctionsVersion>v4</AzureFunctionsVersion>. If you recently upgraded the Core Tools, also run dotnet clean and rebuild.

Conclusion

We went from an empty directory to a running HTTP API with three production patterns:

Query strings for simple reads (GET /api/Hello?name=Azure)
JSON bodies for mutations (POST /api/orders)
Route parameters for resource-oriented endpoints (GET /api/products/electronics/42)

All running locally, no Azure subscription needed.

The isolated worker model with ASP.NET Core integration gives you familiar types—HttpRequest, IActionResult, [FromBody]—so writing Azure Functions feels like writing any other .NET web API. The main difference is that Azure handles the hosting, scaling, and infrastructure.

The code samples in this article are deliberately simple. In a real project, you'd add input validation, error handling, and probably connect to a database or external service. But the patterns are the same—the [HttpTrigger] attribute, the route configuration, the model binding. Once you understand these building blocks, everything else is regular C#.

All code from this article is available in the azure-functions-samples repository—clone it, run func start, and experiment.

What's Next in This Series

Part 3: Beyond HTTP Triggers explores timer, queue, and blob triggers—the event-driven patterns that make Functions powerful.

Part 4: Local Development Setup covers the tools, debugging techniques, and productivity tips that make daily development smooth.

Part 5: Understanding the Isolated Worker Model explains what "isolated" means, why Microsoft created this model, how it differs from the legacy in-process model, and what it means for your code.

And yes—we'll cover deploying to Azure with CI/CD via GitHub Actions later in the series, so everything you're building locally will make it to the cloud.

I Replaced nvm, Homebrew Go, and Homebrew Python with a Single Tool

Martin Oehlert — Tue, 10 Feb 2026 09:11:54 +0000

I maintain a symlink-based dotfiles repo for macOS/zsh. Over time, I'd accumulated three different approaches to managing runtime versions: nvm for Node.js, brew install go for Go, and brew install python@3.13 for Python. Each had its own quirks, its own update ritual, and its own startup cost. mise consolidates all of them into one tool with a single config file.

This article walks through the actual migration: what changed, what broke, and the non-obvious tricks that made it worth doing.

The starting point: an nvm lazy-load hack

nvm is slow. Loading it adds 300-500ms to every new shell. My workaround was a lazy-load wrapper in zprofile that deferred the cost until you actually called node, npm, or friends:

# NVM (lazy-loaded for fast startup)
export NVM_DIR="$HOME/.nvm"

_nvm_lazy_load() {
  unfunction nvm node npm npx corepack 2>/dev/null
  [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
  [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
}

nvm()      { _nvm_lazy_load; nvm "$@" }
node()     { _nvm_lazy_load; node "$@" }
npm()      { _nvm_lazy_load; npm "$@" }
npx()      { _nvm_lazy_load; npx "$@" }
corepack() { _nvm_lazy_load; corepack "$@" }

This worked, but it was 15 lines of shell plumbing to avoid a startup penalty from a tool that only manages Node. Go and Python had no version management at all — I just installed whatever Homebrew gave me.

The mise config

mise replaces all of that with a TOML file:

[tools]
node = "22"
go = "1.24"
python = "3.13"

[settings]
idiomatic_version_file = true

That's it. mise install downloads the right versions. The idiomatic_version_file setting means mise reads .nvmrc, .node-version, .python-version, and .go-version files from existing projects — so teams using nvm or pyenv don't need to change anything.

Shell integration: the dual activation trick

This is the part that took some thought. mise offers two modes:

Shims (mise activate zsh --shims): Lightweight stubs in ~/.local/share/mise/shims/ that resolve to the right binary. Fast, works everywhere, but they don't auto-switch versions when you cd into a project with an .nvmrc.
Activate (mise activate zsh): Hooks into your shell's precmd/chpwd to dynamically update PATH. Supports auto-switching, but doesn't run in non-interactive contexts (scripts, IDE terminals running commands, cron jobs).

You need both.

In zprofile (runs for all sessions, including non-interactive):

# Mise — shims for non-interactive sessions (scripts, IDEs, cron)
eval "$(mise activate zsh --shims)"

In plugins.zsh (sourced only in interactive shells via zshrc):

_cache_source mise mise activate zsh

The activate call in interactive shells overrides the shims with real PATH entries, enabling directory-aware version switching. Non-interactive sessions fall back to shims, which resolve to whatever version the config specifies.

The `_cache_source` + zcompile trick

That _cache_source call above is doing more than it looks. Running mise activate zsh generates a shell script on every new shell — and that generation adds 25-300ms depending on the machine. For a shell that opens in 50ms total, that's unacceptable.

The solution: cache the output and compile it to zsh bytecode.

_cache_source() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/$name.zsh"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
    zcompile "$cache_file" 2>/dev/null
  fi
  source "$cache_file"
}

Here's what it does:

Runs mise activate zsh and captures the output to a cache file
Compiles it to zsh bytecode with zcompile (creates a .zwc file)
Sources the cached file on every subsequent shell open
Regenerates after 24 hours (the (N.mh+24) glob qualifier checks mtime)

Why does the compiled version load faster? When you source a plain .zsh file, zsh reads the text, tokenizes the shell syntax, and parses it into an internal representation — every single time. zcompile does that work once and writes the result as a .zwc file — a pre-parsed "wordcode" format that zsh can memory-map and load directly, skipping the tokenize-and-parse steps entirely. For a large generated script like mise activate output, this eliminates the most expensive part of source.

The clever bit is that zsh handles .zwc lookup transparently. When you run source foo.zsh, zsh first checks for foo.zsh.zwc. If the .zwc exists and is newer than the source file, zsh loads the compiled version without being told to. This means _cache_source doesn't need any special logic to prefer the compiled file — source "$cache_file" does the right thing on its own.

And if the .zwc is stale or missing? Zsh silently falls back to parsing the source file the normal way. Nothing breaks — you just lose the speed benefit until the cache regenerates. A stale .zwc can never serve incorrect code because zsh won't use it if the source has changed. This makes the whole approach safe to leave running unattended.

The result: mise activation costs <5ms instead of 25-300ms. This same function works for any "run a command, source the output" pattern — I use it for fzf, direnv, and mise.

This is probably the most reusable thing in the whole migration. If you maintain a zsh config and source any tool's init or activate output, wrap it in something like this.

For the full story on this caching approach — including a subtle glob qualifier bug that silently breaks it — see From 1.4s to 53ms: Optimizing zsh Startup on macOS.

Brew changes

The cleanup was straightforward:

Remove:

nvm — replaced by mise
node — installed by mise
go — installed by mise
python@3.13 — installed by mise
yarn — moved to corepack (see below)

Added:

mise

One gotcha: some Homebrew formulae declare node as a dependency. In my case, markdownlint-cli2 depends on the Homebrew node formula. Removing node from the Brewfile triggers warnings on brew bundle, but it's cosmetic — mise's shims satisfy the actual runtime need. The formula's dependency declaration is about the build, not about your shell having node on PATH. I left it as-is and the warnings are harmless.

Corepack for yarn

With nvm gone, yarn no longer comes from Homebrew either. Node ships with corepack, which manages yarn (and pnpm) natively:

corepack enable

This creates symlinks inside the Node install directory. The catch: when mise installs a new Node version, those symlinks live in the old version's directory. You need to re-run corepack enable after mise install node@<new-version>. It's a one-liner, but easy to forget when you bump Node versions.

The migration procedure

The key insight is that nvm and mise can coexist. This makes the migration safe to do in phases:

Phase 1 — Install mise alongside nvm:

brew install mise
Create mise/config.toml with your current versions
Add the dual activation (shims in zprofile, activate in plugins.zsh)
Open a new shell, verify node --version, go version, python3 --version

Phase 2 — Verify everything works:

Run your builds, tests, dev servers
Check IDE integration (VS Code, JetBrains)
Verify non-interactive contexts: zsh -c 'node --version'
Run corepack enable and confirm yarn --version

Phase 3 — Remove nvm:

Delete the lazy-load block from zprofile
Remove nvm, node, go, python@3.13, yarn from Brewfile
Run brew bundle cleanup --force
Commit

Safety net: nvm's data (~/.nvm/) stays untouched through all of this. If something breaks, you can restore the old zprofile block and you're back to where you started. The whole thing is one git checkout -- shell/zprofile away from reverting.

`.nvmrc` compatibility

If your team uses .nvmrc files (and most Node teams do), the idiomatic_version_file = true setting in mise's config handles it. When you cd into a directory with an .nvmrc, mise reads it and switches to the specified Node version — same as nvm would.

This also works for .node-version, .python-version, and .go-version. So mise supports the conventions from nvm, nodenv, pyenv, and goenv without any extra configuration.

Final result

The zprofile went from 30 lines to 18. The nvm lazy-load hack — 15 lines of shell functions — became a single eval line. Three separate version management approaches (nvm, Homebrew Go, Homebrew Python) became one config file.

Shell startup stayed at ~0.05s thanks to the caching strategy. The dual activation means shims handle non-interactive contexts while the full activate gives you directory-aware switching in your terminal.

The commit tells the story:

Replace nvm with mise for Node.js, Go, and Python version management

8 files changed, 17 insertions(+), 19 deletions(-)

More deletions than insertions. That's usually a good sign.

What else mise can do

This article focused on version management, but mise is a broader dev environment tool. Here's what else it offers once you have it installed.

Task runner

mise has a built-in task runner that replaces Makefiles and npm scripts. Tasks defined in mise.toml (or as standalone scripts in a mise-tasks/ directory) run with the full mise environment — correct tool versions and env vars already set. Dependencies between tasks execute in parallel by default, and mise watch re-runs tasks on file changes. For projects that already have a mise.toml for version management, adding tasks means one fewer tool in the chain.

Environment variables

The [env] section in mise.toml sets project-level environment variables that activate when you cd into the directory — the same behavior as direnv, without a separate tool. It supports dotenv files, required variables with validation, and redactions for secrets that shouldn't appear in logs. Earlier in this article, _cache_source caches direnv's activation output alongside mise's — mise's native env management could replace direnv entirely, removing one more tool from the shell startup chain.

Hooks

mise can run shell commands on directory enter/leave events and after tool installations. The postinstall hook is particularly relevant to this migration — it could automate the corepack enable step that's currently manual after Node upgrades.

Lockfile for reproducible environments

mise.lock pins exact tool versions and checksums per platform, similar to package-lock.json. For teams sharing a mise.toml, the lockfile ensures everyone gets the same binary — not just the same version range. Enable it with mise settings lockfile=true.

This article covered the version management migration, but mise's scope goes well beyond that — it's closer to a unified dev environment than a version manager.

The full dotfiles repo and migration commit are available on GitHub. The _cache_source function lives in shell/zshrc.d/completions.zsh if you want to steal it.

From 1.4s to 53ms: Optimizing zsh Startup on macOS

Martin Oehlert — Mon, 09 Feb 2026 07:29:09 +0000

Every time I opened a terminal, I waited. Not long — maybe a second and a half — but long enough to notice. Long enough to be annoying. I finally decided to profile my zsh startup, and what I found took it from 1.4 seconds down to 53 milliseconds.

Here's what I learned.

Profiling with zprof

Zsh has a built-in profiler. Add zmodload zsh/zprof at the top of your .zshrc and zprof at the bottom, then open a new shell:

# top of .zshrc
zmodload zsh/zprof

# ... your config ...

# bottom of .zshrc
zprof

My initial profile told a clear story:

Culprit	Time	% of startup
NVM (`nvm.sh`)	~430ms	31%
Completion subprocesses (kubectl, helm, gh, ...)	~400ms	29%
`compinit` (full rebuild every time)	~240ms	17%
`brew shellenv`	~30ms	2%
`go env GOPATH`	~20ms	1%
Everything else	~280ms	20%

Four of these five are subprocess calls — things like eval "$(brew shellenv)" or source <(kubectl completion zsh) that fork a process just to produce some static text. That's the low-hanging fruit.

Optimization 1: Lazy-load NVM

NVM was the single biggest offender. Sourcing nvm.sh on every shell startup cost ~430ms, and I don't use node in every terminal session. The fix: wrapper functions that defer loading until you actually call nvm, node, npm, etc.

Before:

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

After:

export NVM_DIR="$HOME/.nvm"

_nvm_lazy_load() {
  unfunction nvm node npm npx corepack 2>/dev/null
  [ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
  [ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"
}

nvm()      { _nvm_lazy_load; nvm "$@" }
node()     { _nvm_lazy_load; node "$@" }
npm()      { _nvm_lazy_load; npm "$@" }
npx()      { _nvm_lazy_load; npx "$@" }
corepack() { _nvm_lazy_load; corepack "$@" }

The wrapper functions replace themselves on first call via unfunction, then delegate to the real command. Cost at startup: zero. Cost on first node invocation: ~430ms (once).

Optimization 2: Hardcode static values

Several lines in my config were spawning subprocesses to compute values that never change:

# Before — subprocess every startup
eval "$(/opt/homebrew/bin/brew shellenv)"
export PATH="$PATH:$(go env GOPATH)/bin"
. "$HOME/.cargo/env"

These produce the same output every time. Just paste the result directly:

# After — zero subprocesses
export HOMEBREW_PREFIX="/opt/homebrew"
export HOMEBREW_CELLAR="/opt/homebrew/Cellar"
export HOMEBREW_REPOSITORY="/opt/homebrew"
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
[ -z "${MANPATH-}" ] || export MANPATH=":${MANPATH#:}"
export INFOPATH="/opt/homebrew/share/info:${INFOPATH:-}"

export GOPATH="$HOME/go"
export PATH="$PATH:$GOPATH/bin"

export PATH="$HOME/.cargo/bin:$PATH"

Leave a comment like # regenerate with: brew shellenv so future-you knows where the values came from.

Optimization 3: Cache completions into fpath

This was the big one. My original config eagerly sourced completions from 12 different tools on every shell startup:

# Before — 12 subprocesses, every startup
command -v kubectl  &>/dev/null && source <(kubectl completion zsh)
command -v helm     &>/dev/null && source <(helm completion zsh)
command -v minikube &>/dev/null && source <(minikube completion zsh)
command -v gh       &>/dev/null && source <(gh completion -s zsh)
# ... 8 more tools

Each source <(tool completion zsh) forks a subprocess AND evaluates thousands of lines of shell code. Minikube's completion alone is 5,000 lines.

The fix has two parts:

For completions: write them to files in an fpath directory. Compinit loads these lazily — only when you actually press TAB on that command:

ZSH_COMP_CACHE="$HOME/.zsh-completion-cache"
[[ -d "$ZSH_COMP_CACHE" ]] || mkdir -p "$ZSH_COMP_CACHE"

_cache_fpath() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/_$name"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
  fi
}

command -v kubectl &>/dev/null && _cache_fpath kubectl kubectl completion zsh
command -v helm    &>/dev/null && _cache_fpath helm    helm completion zsh
# ... etc

fpath=($ZSH_COMP_CACHE $fpath)

For plugins that must run at startup (fzf keybindings, direnv hook, oh-my-posh prompt), cache their init output and zcompile for faster sourcing:

_cache_source() {
  local name="$1"; shift
  local cache_file="$ZSH_COMP_CACHE/$name.zsh"
  local -a stale=($cache_file(N.mh+24))
  if [[ ! -f "$cache_file" ]] || (( $#stale )); then
    "$@" > "$cache_file" 2>/dev/null
    zcompile "$cache_file" 2>/dev/null
  fi
  source "$cache_file"
}

_cache_source fzf fzf --zsh
_cache_source direnv direnv hook zsh
_cache_source oh-my-posh oh-my-posh init zsh --config ~/.poshthemes/theme.omp.json --print

Both functions use a 24-hour cache expiry via zsh glob qualifiers. Delete ~/.zsh-completion-cache to force a refresh.

I also cached compinit itself — a full rebuild only runs once per day, and otherwise compinit -C skips straight to the dump file:

autoload -Uz compinit
local -a zcompdump_stale=(~/.zcompdump(N.mh+24))
if (( $#zcompdump_stale )); then
  compinit
else
  compinit -C
fi
{ zcompile ~/.zcompdump } &!

The bug that almost ruined everything

After implementing all of this, I ran time zsh -i -c exit. The result: 1.59 seconds. Slower than before.

I profiled again and saw this:

num  calls                time            self            name
-----------------------------------------------------------------
 1)   15   1180.06  97.34%  1169.02  96.43%  _cache_completion
 2)    1     26.83   2.21%     7.49   0.62%  compinit

The caching function was taking 97% of startup time across 15 calls. The caches existed on disk but were being regenerated every single time. The staleness check was broken.

I restructured the approach — separating completions (fpath-based, lazy) from plugins (source-based, eager) — and tried again. Same problem: _cache_fpath at 72%, compinit doing full rebuilds.

The bug was in this line:

if [[ ! -f "$cache_file" || -n "$cache_file"(#qN.mh+24) ]]; then

This looks reasonable. The glob qualifier (#qN.mh+24) means "match if the file is older than 24 hours, with N (nullglob) to return empty string if no match." The -n test checks if the result is non-empty.

The problem: glob qualifiers don't expand inside [[ ]].

Zsh's [[ ]] conditional construct does not perform filename generation (globbing). The string "$cache_file"(#qN.mh+24) is treated as the literal path with (#qN.mh+24) appended as text. Since that string is always non-empty, the condition is always true. Every cache was being regenerated on every startup. The caching was doing nothing.

The same bug affected the compinit staleness check:

# Also broken — compinit was doing a full rebuild every time
if [[ -n ~/.zcompdump(#qN.mh+24) ]]; then

The fix: expand the glob into an array variable first, then check its length:

local -a stale=($cache_file(N.mh+24))
if [[ ! -f "$cache_file" ]] || (( $#stale )); then

Regular variable assignments DO perform globbing. The (N.mh+24) qualifier (no #q prefix needed outside [[ ]]) expands the glob, and $#stale gives us the match count. If the file is older than 24 hours, stale contains one element; otherwise it's empty.

This is a subtle footgun. The code looks correct, it doesn't produce errors, and the caches are created — they're just never reused. Without profiling, you'd never know.

Result

$ time zsh -i -c exit
zsh -i -c exit  0.03s user 0.02s system 93% cpu 0.053 total

53 milliseconds. A 96% reduction from 1.4 seconds.

Here's what each optimization contributed:

Optimization	Savings
Lazy-load NVM	~430ms
Cache completions into fpath (lazy compinit)	~500ms
Cache plugin init scripts + zcompile	~200ms
Hardcode brew/go/cargo	~50ms
compinit -C (cached dump)	~170ms
Total	~1,350ms

The first shell open after 24 hours takes a couple of seconds to regenerate caches, but every subsequent shell is instant. You can force a full refresh anytime:

rm -rf ~/.zsh-completion-cache ~/.zcompdump*

Takeaways

Profile first. zprof told me exactly where the time was going. Don't guess.
Subprocess calls add up. Each eval $(...) or source <(...) forks a process. Twelve of them cost almost a full second.
fpath > source for completions. Compinit loads completion functions lazily from fpath. Don't eagerly source thousands of lines you might never use.
Test your caching actually works. A cache that regenerates every time is worse than no cache — it has the overhead of both the generation AND the file I/O.
Glob qualifiers don't work inside [[ ]]. This is the kind of bug that looks correct, produces no errors, and silently destroys your performance. Expand globs into variables first.