For the complete documentation index, see llms.txt. This page is also available as Markdown.

Azure Functions

BoxLang Runtime for Microsoft Azure Functions! Serverless for the win!

What is Azure Functions?

Azure Functions is a serverless computing service provided by Microsoft Azure that lets you run code without provisioning or managing servers. It automatically scales applications by running code in response to events and allocates compute resources as needed, allowing developers to focus on writing code rather than managing infrastructure (https://learn.microsoft.com/en-us/azure/azure-functions/).

The BoxLang Azure Functions Runtime allows you to code in BoxLang and create Azure Functions in this ecosystem. We provide you a nice template so you can work with serverless: https://github.com/ortus-boxlang/boxlang-starter-azure-functions. This template will give you a turnkey application with features like:

  • Unit and Integration Testing

  • Java dependency management via Gradle

  • BoxLang dependency management

  • Class compilation caching for improved performance

  • Configuration management with environment overrides

  • Official Azure Functions Gradle plugin for local run and deployment

  • GitHub actions to: test, build and release automatically

Not found

BoxLang Azure Function Handler

Our BoxLang Azure Handler acts as a front controller to all incoming Function executions. It provides you with:

  • Automatic request management to an event structure

  • Automatic logging and tracing

  • Execution of your handler classes by convention

  • Automatic error management and exception handling

  • Automatic response management and serialization

  • Life-Cycle Events via our Application.bx

  • Class compilation caching for improved performance

  • Custom method resolution via headers

The BoxLang Azure runtime provides a pre-built Java entry point already configured to accept an HTTP request as a BoxLang Struct and then output either by returning a simple or complex object or using our response convention struct. Our runtime will automatically convert your results to JSON.

You can see the code for the handler here: https://github.com/ortus-boxlang/boxlang-azure-functions

The handler will look for a Lambda.bx in your package and execute the run() method by convention - the same default handler filename used across all three BoxLang serverless runtimes.

Environment Variables

The following are all the environment variables the Azure Functions runtime can read and detect. If they are set by you or the Azure Functions host, then it will use those values to alter operations.

Environment Variable
Description

BOXLANG_AZURE_ROOT

Root directory for .bx files. Defaults to the Azure-provided AzureWebJobsScriptRoot, else /home/site/wwwroot.

BOXLANG_AZURE_CLASS

Absolute path to the default handler to execute. The default is Lambda.bx at the function root.

BOXLANG_AZURE_DEBUGMODE

Turn runtime debug mode on or off. When enabled, disables handler-class caching so .bx changes are picked up immediately, and enables verbose logging.

BOXLANG_AZURE_CONFIG

Absolute path to a custom boxlang.json configuration for the runtime. Defaults to boxlang.json in the function root.

BOXLANG_ENABLE_ROOT_SCAN

Opts out of the legacy root-directory scan used only when neither manifest.json nor handlers/ is present. Defaults to true. Set to false to restrict that fallback scenario to the default handler only. Shared across every BoxLang serverless runtime (AWS/GCP/Azure).

AzureWebJobsScriptRoot

Function app root directory, set automatically by the Azure Functions host. Used as the fallback for BOXLANG_AZURE_ROOT when that isn't set.

You can also leverage ANY environment variable to configure the BoxLang runtime using our runtime environment conventions.

BoxLang Azure Functions Template

The BoxLang default template for Azure Functions can be found here: https://github.com/ortus-boxlang/boxlang-starter-azure-functions. The structure of the project is the following:

The BoxLang Azure Functions runtime will look for a Lambda.bx in your package by convention and execute the run() method for you.

Key Template Features

  • Configuration Management: boxlang.json controls caching, class generation, logging, and timeouts

  • Official Azure Plugin Integration: azureFunctionsRun/azureFunctionsPackage/azureFunctionsDeploy via the official com.microsoft.azure.azurefunctions Gradle plugin

  • Gradle Dependency Resolution: Automatic dependency management via Gradle

  • Performance Optimizations: Class caching built-in

  • Local Testing: Fast, mock-based integration tests plus a real local HTTP server via azureFunctionsRun

  • AI Development Support: Comprehensive GitHub Copilot instructions for enhanced development experience

AI-Assisted Development: The BoxLang Azure Functions template includes comprehensive GitHub Copilot instructions (.github/copilot-instructions.md) that provide AI assistants with detailed context about:

  • Project architecture and conventions

  • Build system and deployment workflows

  • Convention-based routing patterns

  • Configuration management

  • Testing strategies and file locations

This enables more accurate and contextual assistance when developing BoxLang Azure Functions.

Building and Testing

Lambda.bx

The default handler is a BoxLang class with a single function called run().

Arguments

It accepts three arguments:

Argument
Type
Description

event

Struct

The incoming HTTP request as a BoxLang struct (method, path, headers, body, queryStringParameters, requestContext.http, etc.) - the same shape used by the AWS Lambda and Google Cloud Functions runtimes.

context

Struct

The Azure runtime context struct: functionName, invocationId, requestId.

response

Struct

A BoxLang struct convention for a response.

Event

The event structure is a snapshot of the input to your function. We deserialize the incoming HTTP request for you and give you a nice struct.

Context

This is a BoxLang struct built from Azure's ExecutionContext Java object, which provides invocation metadata. For more information on the underlying Java type, check out Microsoft's Azure Functions Java reference.

Context fields

  • functionName - The name of the Azure Function, from ExecutionContext#getFunctionName().

  • invocationId - The unique identifier for this invocation, from ExecutionContext#getInvocationId(). Use this to correlate with Application Insights traces.

  • requestId - Alias of invocationId, for naming parity with the AWS/GCF context structs.

Response

The response argument is our convention to help you build a nice return structure. However, it is completely optional. You can easily return a simple or complex object from your function, and we will convert it to JSON.

Now you can go ahead and build your function. You can use TestBox to unit test your Lambda.bx, or use the included Java integration test in src/test/java/com/myproject/AzureFunctionIntegrationTest.java, which exercises the full request pipeline against AzureFunctionRunner directly using mock Azure request/context objects - no live Azure environment needed. Just run ./gradlew test or use VSCode BoxLang IDE to run the tests. Now we go to production!

Convention-Based URI Routing

The runtime supports automatic routing using a handlers/ directory convention, allowing you to build multi-class functions with BoxLang easily following our conventions.

When your function is exposed as a URL, the runtime automatically routes to different BoxLang classes under src/main/bx/handlers/ based on the URI path:

Example Multi-Class Structure

Each class should implement a run function:

URI to Class Name Conversion

The routing follows these conventions:

  • /products → handlers/Products.bx

  • /home-savings → handlers/HomeSavings.bx

  • /user-profile → handlers/UserProfile.bx

  • /api/test → handlers/api/Test.bx (nested)

Hyphens are converted to PascalCase for the leaf filename only. Subdirectories under handlers/ can use any case you like and are matched literally (lowercased), so handlers/Api/Test.bx and handlers/api/Test.bx both register as /api/test. Matching is case-insensitive, and the longest matching prefix wins, so a request like /products/categories/electronics still falls through to the flat products route when no more specific nested route exists - a request to a route that isn't registered anywhere just runs Lambda.bx, same as if routing had never happened.

Understanding manifest.json

manifest.json is the routing table behind Convention-Based URI Routing. It's a plain JSON file listing every handler under handlers/, mapped from its route key to its relative file path, plus the default handler and the filenames that can never be routed to. The runtime reads it once, at cold start - it never scans the filesystem at request time.

Example - generated from a handlers/Products.bx and a nested handlers/api/Test.bx:

Creating or recreating it: run the generateManifest Gradle task. It scans handlers/ and rewrites manifest.json next to Lambda.bx:

You'll rarely need to run this by hand - it's wired as a dependency of test, azureFunctionsRun, azureFunctionsPackage, and azureFunctionsDeploy, so it's always regenerated before you test, run, package, or deploy. manifest.json is gitignored; never edit it by hand or commit it, since any change you make is overwritten on the next build.

reserved and defaultHandler are enforced, not just documentation: the runtime actively rejects any handlers entry whose target file matches a name in reserved (merged with the built-in Application.bx and default-handler names), so a manifest can never route to a reserved file no matter what it lists. defaultHandler.file/method is honored as the handler for unmatched routes - falling back to Lambda.bx/run() when absent, invalid, or pointing at a file that doesn't exist. Every handlers entry's file is also checked for existence at cold start; a listed file that isn't actually there is skipped with a warning rather than silently registered.

If it's ever missing or invalid at cold start (for example, a deployment package built without running generateManifest), the runtime falls back to scanning handlers/ directly, and if that directory doesn't exist either, to scanning the function root for backward compatibility with pre-handlers/ deployments - gated behind BOXLANG_ENABLE_ROOT_SCAN (default true) and always excluding Application.bx and Lambda.bx from that last, legacy tier. Either fallback logs a WARNING in your function logs listing every handler it discovered and registered, so a stale or missing manifest is never a silent surprise - check Application Insights / the Azure portal's log stream if routing looks off after a deploy.

Application Lifecycle

Your project's root Application.bx fires for every invocation - no matter which handler ends up serving it, the default Lambda.bx or any routed class under handlers/. There's a single Application.bx per deployment; you don't need (and can't have) a separate one per handler.

This means a datasource, cache region, or interceptor registered in onApplicationStart() is available to every handler in handlers/, not just Lambda.bx. If your handler is missing configuration you expected Application.bx to provide, confirm it lives at the function root (src/main/bx/Application.bx) alongside Lambda.bx, not nested under handlers/.

Wrapping Responses and Handling Errors

run() and every request lifecycle hook (onRequestStart, onRequestEnd, onError, onAbort) receive the same response struct as their last argument. The value your handler returns is stored in response.body before onRequestEnd runs, so a hook can wrap or replace it. This lets you put every result in a standard ok or error object in one place:

What the caller receives for a handler that returns { id: 1, name: "Luis" }, or throws boom:

Case
Response

Success

200 with { "ok": true, "data": { "id": 1, "name": "Luis" } }

Handled error

500 with { "ok": false, "error": "boom" }

Unhandled error (no onError)

The invocation fails

The request lifecycle hooks and their arguments:

Hook
Arguments

onRequestStart

target, event, context, response

onRequestEnd

target, event, context, response

onError

exception, eventName, event, context, response

onAbort

target, event, context, response

onApplicationStart and the session hooks are fired by BoxLang itself, not per request, and receive no request data.

A few rules to know:

  • onRequestEnd runs before onError. On a failed request onRequestEnd wraps the empty body first, then onError overwrites it, so onError always has the last word.

  • A handled error defaults the status to 500. Set response.statusCode in onError to change it, for example 404 for a not found exception.

  • If Application.bx defines onError, the error counts as handled whatever the hook returns. To fail the invocation instead, rethrow from onError or do not define it.

  • Hooks that do not declare the extra response argument keep working unchanged.

Multiple Functions Header

The runtime also allows you to create other functions inside of your Lambda.bx (or any handlers/ class) that can be targeted when your Azure Function is exposed as a URL, by using the following header when executing your function:

This makes it incredibly flexible where you can respond to that incoming header in a different function than the one by convention.

This header can only ever reach a public (or remote) method - BoxLang's own scope rules mean a private method is never even visible to the runtime's dispatch mechanism, the same rule that governs any other BoxLang class. Don't mark a method public if you don't want it externally callable this way.

Azure Function Modules

You can use any BoxLang module with the BoxLang Azure Functions runtime by installing them to the src/resources/boxlang_modules folder. All modules placed there during the build process will be packaged into your deployment.

Local Development & Testing

The template provides two layers of local testing:

Fast, Mock-Based Integration Tests

These run against AzureFunctionRunner directly with mock Azure request/context objects - no network, no Core Tools, no live Azure environment needed. This is what CI runs.

Real Local HTTP Server

Then test with curl in another terminal:

Set BOXLANG_AZURE_DEBUGMODE=true in local.settings.json to enable verbose logging and disable class caching, so .bx file changes are reflected immediately without a restart.

Deploy to Azure

You can deploy your function using the official Azure Functions Gradle plugin or GitHub Actions.

Gradle Deployment

The azurefunctions {} block in build.gradle reads all deployment settings from these environment variables - nothing is hard-coded, so the same build.gradle works in CI/CD and locally.

GitHub Actions Deployment

Manual Deployment via the Azure Portal

  1. Build the project: ./gradlew azureFunctionsPackageZip

  2. Log in to the Azure Portal and create (or select) a Function App

  3. Choose Java 21 as your runtime stack and Linux as your OS

  4. Deploy the generated zip from build/azure-functions/ using your preferred method (Azure CLI func azure functionapp publish, the portal's deployment center, or a CI/CD pipeline)

Runtime Source Code

The Azure Functions Runtime source code can be found here: https://github.com/ortus-boxlang/boxlang-azure-functions

Performance Best Practices

For optimal performance with the BoxLang Azure Functions runtime:

  1. Enable Class Caching: Use trustedCache=true in your boxlang.json for production

  2. Memory/Plan Allocation: Consider a Premium plan for consistent cold-start performance in production

  3. Static Initialization: The runtime already uses static blocks for expensive one-time setup - avoid adding your own heavy work to Application.bx's onApplicationStart()

  4. Early Returns: Validate input early and return immediately on errors

We welcome any pull requests, testing, documentation contributions, and feedback.

Last updated

Was this helpful?