Azure Functions configuration

The configure method

The static Configure{FunctionName} method is discovered by the source generator and called once per endpoint at host startup. Parameters are matched by type against the properties of IHostApplicationBuilder. Any interface type implemented by those properties is accepted:

Parameter	Source	Use
`EndpointConfiguration`	—	Required. Configures the endpoint.
`IServiceCollection`	Adapted from `builder.Services`	Optional. Registers services scoped to this endpoint only.
`IConfigurationManager`	`builder.Configuration`	Optional. Reads application configuration.
`IHostEnvironment`	`builder.Environment`	Optional. Inspects the hosting environment, for example to differentiate development and production.
`IDictionary<object, object>`	`builder.Properties`	Optional. Shares state between host configuration and endpoint configuration.

Declare only the parameters needed, EndpointConfiguration must be first:

Because a single Functions app can host multiple endpoints, the IServiceCollection passed to the configure method is an adapted collection that scopes registrations to that endpoint. Services registered this way are resolvable only within the endpoint's message-handling pipeline (handlers, sagas, features, and installers). To resolve such a dependency outside the endpoint (for example, in an HTTP-triggered function), use keyed services with the endpoint name (the function name) as the key, or register the service on the global IServiceCollection in Program.cs instead. For more details, see Endpoint-scoped dependencies.

Logging and metrics are host-level concerns. Configure them on the host builder in Program.cs, not in the per-endpoint Configure{FunctionName} method.

Copy code|Copy usings|Edit

public partial class ShippingEndpoint
{
    [Function("Shipping")]
    [NServiceBusFunction]
    public partial Task Shipping(
        [ServiceBusTrigger("shipping", AutoCompleteMessages = false)]
        ServiceBusReceivedMessage message,
        ServiceBusMessageActions messageActions,
        FunctionContext functionContext,
        CancellationToken cancellationToken = default);

    public static void ConfigureShipping(
        EndpointConfiguration endpointConfiguration,
        IServiceCollection services,
        IConfigurationManager configuration,
        IHostEnvironment environment)
    {
        endpointConfiguration.UseTransport(new AzureServiceBusServerlessTransport(TopicTopology.Default));
        endpointConfiguration.UseSerialization<SystemJsonSerializer>();
        services.AddSingleton(new MyComponent("Shipping"));
        endpointConfiguration.AddHandler<ShipOrderHandler>();

        if (environment.IsProduction())
        {
            endpointConfiguration.AuditProcessedMessagesTo(configuration["audit-queue"] ?? "audit");
        }
    }
}

Transport configuration

Azure Functions endpoints must use AzureServiceBusServerlessTransport. Other transport definitions are currently not supported in this hosting model.

Supported options:

Option	Notes
`HierarchyNamespaceOptions`	Applies hierarchy prefixes to transport addresses and entities created by the transport.
`EnablePartitioning`	Applies when the transport creates queues and topics.
`EntityMaximumSize`	Applies when the transport creates queues and topics.
`AutoForwardDeadLetteredMessagesToErrorQueue`	Enabled by default. Applies to transport-created receive queues.
`MaxDeliveryCount`	Applies when the transport creates queues. In this hosting model, `AzureServiceBusServerlessTransport` defaults `MaxDeliveryCount` to `100`, not `int.MaxValue` like `AzureServiceBusTransport`.
`ThrowOnMissingTopicWhenPublishing`	Controls whether publishing to a non-existent topic throws after logging a warning.

Other receive-side Azure Service Bus transport settings, such as prefetch count and lock renewal, are controlled by Azure Functions rather than by AzureServiceBusServerlessTransport in this hosting model.

Explicit handler and saga registration

Assembly scanning is not available in this hosting model because a single Functions app can host multiple endpoints. As a secondary effect, avoiding assembly scanning also improves cold startup times.

Handlers and sagas must therefore be registered explicitly. See Registering Handlers and Sagas for the available registration approaches in NServiceBus 10.2, and Disable assembly scanning for the caveats and additional manual registration requirements. Handlers that are not registered will not be invoked.

Connection configuration

The Azure Service Bus connection will by default be read from an appSetting named AzureWebJobsServiceBus unless explicitly configured via the connection parameter on the [ServiceBusTrigger] or NServiceBusSendOnlyFunction attributes.

Queue name resolution

The queue that the endpoint receives from is taken from the queueName passed to the [ServiceBusTrigger] attribute. No separate receive queue name is configured in Configure{FunctionName}.

The queue name supports functions binding expressions.

Transactions

Azure Functions endpoints only supports TransportTransactionMode.ReceiveOnly.

Recoverability

In addition to the standard recoverability provided by NServiceBus the package also automatically enables dead-letter queue forwarding to the error queue, so dead-lettered messages can be managed alongside other failed messages by tools such as ServicePulse.

For details on the dead-letter behavior and configuration options, see dead-lettering in the Azure Service Bus transport documentation.

Provisioning

Queues and other entities in the Azure Service Bus namespace can be provisioned using EnableInstallers().

Alternatively, provision entities explicitly using the asb-transport command-line tool.

The Azure Service Bus transport defaults MaxDeliveryCount to 100. When provisioning entities with installers, the asb-transport tool, or by hand, set MaxDeliveryCount to match so the namespace and the transport agree. When using the CLI, pass --maximum-delivery-count 100 and include dead-letter queue forwarding using --forward-dlq-to error.

Startup diagnostics

Startup diagnostics are not written by default in this hosting model. Use LogDiagnostics() to write them to the Functions host log stream and any configured destination such as Application Insights. For the available LogDiagnostics() behavior and options, see Writing diagnostics to the log.

Custom diagnostics writer

For full control over the diagnostic output (for example, to persist diagnostics beyond the function's execution lifetime or to aggregate diagnostic data from multiple function instances), configure a custom diagnostics writer on the endpoint configuration.

Host ID

The package derives the NServiceBus Host ID from the Azure Functions hosting environment so scaled-out instances can be identified consistently.

The Host ID resolution order is:

WEBSITE_INSTANCE_ID when running in Azure Functions on App Service
CONTAINER_NAME when running in Azure Container Apps
Environment.MachineName for local development

When using WEBSITE_INSTANCE_ID, it is recommended to configure ServicePulse not to track heartbeats for these instances to avoid false negatives.

If needed, use the guidance in Overriding the host identifier to take full control over the Host ID and keep it stable across restarts and deployments.