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
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
eventstructureAutomatic 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.bxClass 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.
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.
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.jsoncontrols caching, class generation, logging, and timeoutsOfficial Azure Plugin Integration:
azureFunctionsRun/azureFunctionsPackage/azureFunctionsDeployvia the officialcom.microsoft.azure.azurefunctionsGradle pluginGradle 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
azureFunctionsRunAI Development Support: Comprehensive GitHub Copilot instructions for enhanced development experience
Building and Testing
Lambda.bx
The default handler is a BoxLang class with a single function called run().
Arguments
It accepts three arguments:
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, fromExecutionContext#getFunctionName().invocationId- The unique identifier for this invocation, fromExecutionContext#getInvocationId(). Use this to correlate with Application Insights traces.requestId- Alias ofinvocationId, 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.
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:
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:
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:
onRequestEndruns beforeonError. On a failed requestonRequestEndwraps the empty body first, thenonErroroverwrites it, soonErroralways has the last word.A handled error defaults the status to
500. Setresponse.statusCodeinonErrorto change it, for example404for a not found exception.If
Application.bxdefinesonError, the error counts as handled whatever the hook returns. To fail the invocation instead, rethrow fromonErroror do not define it.Hooks that do not declare the extra
responseargument 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.
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
Build the project:
./gradlew azureFunctionsPackageZipLog in to the Azure Portal and create (or select) a Function App
Choose Java 21 as your runtime stack and Linux as your OS
Deploy the generated zip from
build/azure-functions/using your preferred method (Azure CLIfunc 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:
Enable Class Caching: Use
trustedCache=truein yourboxlang.jsonfor productionMemory/Plan Allocation: Consider a Premium plan for consistent cold-start performance in production
Static Initialization: The runtime already uses static blocks for expensive one-time setup - avoid adding your own heavy work to
Application.bx'sonApplicationStart()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?
