DEV Community: James Randall

Training a Neural Network in 16-bit Fixed Point on a 1982 BBC Micro

James Randall — Tue, 10 Mar 2026 13:17:31 +0000

The source code for this post can be found on GitHub.

In my previous post on neural networks we went through the basic concepts and simple mathematics involved in training and running a neural network. It's so simple that it gave me an idea: could I run this on an 8-bit micro. Namely a BBC Micro.

I don't think it's really foreshadowing to say that yes, you can run a neural network on a BBC Micro. I can't embed the emulator here but you can see it in action below or view it online here.

Unsurprisingly its rather slow, and this is the "fast" 6502 version running at 4x speed - so imagine the BBC Basic version running at 1x speed! If you refresh the page the network is seeded with random weights and biases so you can watch different convergences.

So, how does it work? In exactly the same way.

The mathematics and setup are literally what we saw before just converted into 6502. I actually did this in two stages. Stage 1 was converting it to run in BBC Basic - I didn't really worry about performance but it really was torturously slow and so I did the obvious optimisation: used a lookup table for the sigmoid function. That made it faster but I knew going in I'd have to use 6502.

And so stage 2 was to take this and port it over to 6502. If you want to take a look at the source then the key routines are:

Routine	Description
`neg16`	Two's complement negation of a 16-bit value at a zero-page address. EORs both bytes with `0xFF` and adds 1.
`mulq`	Q4.11 fixed-point multiply. Extracts the result sign, makes both operands positive, runs a 16×16→32 shift-and-add loop, then shifts right by 11 to re-normalise - a few more details are below.
`sigmd`	Sigmoid activation via 256-entry LUT. Clamps out-of-range inputs, otherwise offsets and indexes into a pre-built table of Q4.11 sigmoid values.
`fwdps`	Forward pass. Computes weighted sums plus biases for all four hidden neurons through sigmoid, then the output neuron the same way.
`bwdps`	Backpropagation. Computes output delta via sigmoid derivative, propagates error back through output weights to get hidden deltas, then updates all weights and biases using the learning rate.
`train`	Training loop over all four XOR samples. Loads each input/target pair, calls `fwdps` then `bwdps`, and stores the output predictions.
`render`	Flicker-free connection redraw. Waits for VSYNC, erases all lines in black, then redraws each connection colour-coded by weight magnitude (green/red/white).
`plotln`	Draws a single line between two screen coordinates read from the connection table via indirect indexed addressing.
`setgcl`	Sets the graphics foreground colour by writing VDU 18,0,n via OSWRCH.
`advcp`	Advances the connection table pointer by 10 bytes (one entry).
`rstcp`	Resets the connection table pointer back to the start of the table.

When you do something like this you immediately you have to consider a key question - how are you going to do floating point maths in 8-bit registers. Fixed point maths was common back in the day and you have to decide how many bits to use for the integer portion and how many bits for the fractional portion. I went with a Q4.11 scheme: 4 integer bits, 11 fractional bits and 1 sign bit. I picked this just from my observations of the neural net running in TypeScript. It felt like the right balance of integer range and precision.

Addition and subtraction just work, we don't really need to do anything. Multiplication is a bit more complex. If you multiply two Q4.11 numbers together you get a Q8.22 result. You need to shift it right by 11 bits to get back to Q4.11.

The mulq routine handles this in stages. First it stashes the result sign (XOR of the two sign bits) and makes both operands positive — the 6502 has no signed multiply, so it's easier to work in magnitudes and reapply the sign at the end. Then it does a standard 16×16→32-bit shift-and-add loop: 16 iterations, shifting the multiplier right one bit each time, conditionally adding the multiplicand into the upper half of the result.

The fixed-point correction is the clever bit. The 32-bit result sits in mr0..3. The code takes bytes 1 and 2 (skipping byte 0), which is an implicit 8-bit right shift. Then three explicit LSR / ROR cascades shift right by another 3 bits. That gives 8 + 3 = 11 total, exactly the Q4.11 fractional width. The result lands in t0 ready for use.

I can't take the credit for any of that cleverness - these were techniques established by the incredible coders of the day.

The nice thing about the code is that it makes use of one of the great features about the BBC - you could mix and match BBC Basic and 6502. It really was very cool - you could gradually convert a program over to 6502 a piece at a time and, if you want, leave the bits best suited to BASIC in BASIC and the bits that needed to run fast in 6502. It really was an amazing machine for coding on. In this example the Sigmoid lookup table is still built in BASIC - we're only running it once at the start, no need to break our brain converting this into 6502.

I have to say Claude Code was invaluable in getting this to work in 6502 without spending crazy amounts of time on it. It wasn't perfect but by breaking the problem down into parts it was pretty fast to get going and helped me prove that yes, you can run a neural network on an 8-bit micro.

If anyone knows Steve Furber or Sophie Wilson... would be great if you could share with them. I'd love to say thanks to both of them for the joy they've brought me through the years. It all started with their machine.

The emulation is provided by the amazing jsBeeb.

AI Can't Recreate Thrust (But It Can Help You Understand It)

James Randall — Fri, 06 Mar 2026 19:12:30 +0000

I asked Claude to recreate the classic 1986 game Thrust for me in the browser. It created slop but then things spiralled out of control.

Thrust was one of my favourite games on the BBC Micro — written by Jeremy C. Smith and published in 1986, it's a deceptively deep game with amazing physics and gameplay. You pilot a ship through caverns, collecting fuel, avoiding turret fire, and retrieving a pod for bonus points while fighting gravity and momentum. Jeremy went on to create the even more impressive Exile with Peter Irvin before tragically dying in an accident in 1992. He was somewhere between 16 and 18 when he wrote Thrust. You can play the original online complete with some retro effects.

I've got a BBC Master on the desk beside me and I still occasionally fire up Thrust on there along with some of the other classics. It's one of those games I keep returning to along with Elite, Exile and Holed Out. I've now recreated three of these in different ways... the fourth is looking increasingly unavoidable.

Starting with slop

Anyway. I guess I'd been thinking about Thrust as one morning recently I somewhat casually asked Claude Code to create it for me in the browser. I think I'd been reading the latest proclamations of capability from OpenAI and Anthropic and so I put together quite a comprehensive spec, gave it access to the original disassembled source code, screenshots, and said "go and recreate Thrust for me.".

It created something for which the term slop would be too kind, it very vaguely resembled Thrust — it had the scanline stuff, sort of — but it was truly dreadful. It hadn't even got gravity working right, the ship didn't fall properly, the controls felt weird, and it was just... grim. In some ways its amazing that it created something that sort of worked and sort of looked like Thrust but it was not playable and nothing close to the elegance and beautfy of the real thing.

And that's the thing about a game like Thrust. You could knock out something superficially similar pretty quickly — just run at the device frame rate, use standard delta-time physics, draw some caverns. But it would feel nothing like Thrust. The magic is in the specific timings, the weight of the ship, the way momentum builds. Particularly if you've played the original then those details are everything, and an AI working from a text description, and it turns out even the original source, can't capture them.

The archaeology

But it got me curious. How did the original work? I find the tricks developers used to make this stuff work on the 8-bits fascinating, and it became a bit of an archaeology session. I quickly found this brilliant commented disassembly of the original source by Kieran Connell and found myself feeding it into Claude and asking questions.

This is where things got interesting. Not because AI wrote the code — the code itself isn't complicated, it's a 1986 game that ran in 32K of RAM — but because Claude turned out to be an extraordinary tool for interrogating 6502 assembly. I could feed in a block of disassembled source and ask "how does the level data work?" or "what's the physics model doing here?" and get detailed, accurate explanations of what the original code was doing.

Now to be fair I was working from some commented disassembled source code but even given that it was able to extract information from both the comments and the assembly and come up with detailed descriptions of how the game worked. My sense is without the comments helping to focus it at the right areas it would have been much less useful - but even so, it made the job an awful lot simpler and more enjoyable. And yes it seems likely I'll strip the comments from the code and see how well Claude does then.

While doing this I realised I could use the answers as the basis to recreate the original game and started asking Claude to create specifications for the various subsystems. Most of the specifications I generated can be found in a specs folder in the source code. I might write them up properly at some point but for now they give a good insight into the nuances in the original — there's quite a lot going on, more than I'd realised. For example I'd never noticed that the turrets stop firing for a time if you hit the generator, and there are subtleties in their firing angles that only become apparent when you read the actual code.

The Physics

The physics was one of the most interesting areas to dig into. Thrust uses Q7.8 fixed-point arithmetic — a common technique on 8-bit machines where you don't have floating point hardware. The rotation system uses 32 steps with lookup tables for the force components.

But the really tricky part was timing. My first implementation used the correct constants from the disassembly — the same gravity, the same thrust values, the same drag — but the ship was far too fast and too agile. It didn't have the right weight. The constants were identical to the original so it had to be a timing problem.

And it was. The original doesn't run its physics at the BBC Micro's 50 Hz VSync rate. The tick loop waits at least 3 centiseconds per frame, giving an effective rate of about 33.33 Hz. But it goes further than that: within each tick, physics updates are gated to only 6 active slots per 16-tick window. The core of the physics step looks like this:

/** The 6 active physics slots per 16-tick window */
private static readonly ACTIVE_SLOTS = new Set([0, 3, 5, 8, 11, 13]);

private tickStep(input: ThrustInput): void {
  const slot = this.tickCounter & 0x0F;
  this.tickCounter = (this.tickCounter + 1) & 0xFF;

  // Rotation: 3 out of every 4 ticks, integer steps only
  if ((slot & 0x03) !== 0 && input.rotate !== 0) {
    s.angle = ((s.angle + input.rotate) + 32) % 32;
  }

  const isActiveSlot = ThrustPhysics.ACTIVE_SLOTS.has(slot);

  // Force calculation — active slots only (6 of every 16 ticks)
  if (isActiveSlot) {
    s.forceY += this.gravity;

    if (input.thrust) {
      s.forceY += ANGLE_Y[angleIdx] / (1 << this.massShift);
      s.forceX += ANGLE_X[angleIdx] / (1 << this.massShift);
    }

    // Linear drag
    s.forceX *= 1 - 1/64;   // X: *= 63/64
    s.forceY *= 1 - 1/256;  // Y: *= 255/256
  }

  // Position integration — every tick
  s.x += s.forceX;
  s.y += s.forceY;
}

That gating gives an effective force/drag rate of roughly 12.5 Hz — gravity and thrust only apply on those 6 specific ticks, not every frame. Even rotation has its own gating: it skips every fourth tick. These aren't arbitrary numbers; they're the exact patterns from the 6502 source, and they define the feel of the game - if you pull them around things quickly start to feel off. The asymmetric drag is interesting too — much stronger on the X axis (63/64) than Y (255/256), which is why horizontal movement feels "stickier" than vertical.

Once I got these timings right — matching the original's exact update cadence rather than just its constants — it felt perfect. You can switch between the BBC emulator and my version and the controls feel the same.

That's what became genuinely interesting to me. Creating a Thrust-like game with normal physics is trivial - particularly using a coding AI. Recreating Thrust — with all its specific feel and weight — required understanding exactly how the original worked, right down to the timing of individual physics updates within the game loop.

The Sound

The other area that required some real focus was the sound. When I did my TypeScript version of Elite I sampled the sounds directly from the emulator. That worked because Elite's sounds are quite discrete — short, sharp effects. Though the beam and military laser effects are off. But in Thrust the engine is a continuous drone that responds to key presses, and the explosions have specific envelopes. I could have sampled them but it just felt... wrong.

So instead I decided to take a different approach and instead recreated the SN76489 sound chip (the same chip that was in the Sega Master System, as I learned while working on this) and the BBC MOS interface to it. The MOS — the BBC's Machine Operating System — provided the interface through which games talked to the sound chip, using OSWORD calls and memory-mapped I/O.

A big help in this was the disassembled MOS code that Toby Nelson has put together, along with the BBC Advanced User Guide and the SN76489 chip specifications. I was able to feed all of this into Claude, generate a comprehensive spec for the sound system, and from that build an emulated sound system running in an AudioWorklet. The full BBC MOS envelope processor (OSWORD 7/8) drives the chip emulator on the audio thread.

The result? The sounds are identical. And it would have been really difficult to get that by any other means — it's so timing-specific, so dependent on the exact envelope shapes and chip behaviour, that you really do need to emulate the actual hardware.

The sound system itself is quite elegant in how it layers. At the top level, playing a sound means sending the same OSWORD 7 parameters the original game used — channel, amplitude, pitch, duration:

const sounds = {
  own_gun:     { channel: 0x0012, amplitude: 1,   pitch: 0x50, duration: 2   },
  explosion_1: { channel: 0x0011, amplitude: 2,   pitch: 0x96, duration: 100 },
  explosion_2: { channel: 0x0010, amplitude: 3,   pitch: 0x07, duration: 100 },
  hostile_gun: { channel: 0x0013, amplitude: 4,   pitch: 0x1e, duration: 20  },
  engine:      { channel: 0x0010, amplitude: -10,  pitch: 0x05, duration: 3   },
};

Those parameters feed into a MOS envelope processor that drives the SN76489 chip emulator, both running in an AudioWorklet on the audio thread. The chip emulator generates samples at the hardware level — tone channels with 10-bit period counters, a noise channel with a 15-bit linear feedback shift register, and a volume table with -2dB per step matching the original silicon:

generate(out: Float32Array, offset: number, length: number, sampleRate: number): void {
  const step = 250000.0 / sampleRate; // chip clocks per audio sample

  for (let i = 0; i < length; i++) {
    let sample = 0;

    // Tone channels 0–2
    for (let ch = 0; ch < 3; ch++) {
      this.counter[ch] -= step;
      if (this.counter[ch] <= 0) {
        const p = this.period[ch] || 1024;
        this.counter[ch] += p;
        this.polarity[ch] = -this.polarity[ch];
      }
      sample += this.polarity[ch] * this.vol[ch];
    }

    // Noise channel — 15-bit LFSR
    // ...
    sample += ((this.lfsr & 1) ? 1 : -1) * this.vol[3];
    out[offset + i] = sample;
  }
}

It's emulation all the way down. The MOS ticks at 100 Hz on the audio thread, processing envelopes and updating the chip registers at the same rate the real BBC hardware would have and the resulting sounds are authentic.

The Graphics and Levels

The font, graphics, and level data I was able to extract from the disassembled source relatively easily. You can find a couple of tools in the source that do that — one decodes the level terrain data, another extracts the ship rotation sprites by emulating the BBC's frame buffer and converting the output to PNGs.

I'd initially tried a vector approach for the ship — just drawing it mathematically at each rotation — but it looked rough at BBC resolution as it turned out the original had hard-coded sprites for each of the 32 rotation angles, hand-optimised by Jeremy Smith to look right at each position. Once I extracted and used those actual sprites, it looked correct.

The terrain rendering uses the original's scanline-parity polygon fill — drawing every other line — which gives it that characteristic BBC Micro look. The internal resolution is 320×256, matching the original. My version has a slightly larger viewport — the original has a border around it, likely to keep the scrolling fast enough on the BBC — and I might add a toggle for that at some point.

The Demo Mode

One of the last things I added was the demo mode — the attract sequence where the game plays itself on the title screen. Digging into how the original implemented this was satisfying: it simply injects key presses into the game loop at timed intervals. There's no separate demo renderer — the normal game engine runs with fake inputs from a pair of parallel tables:

// Which keys to hold for each segment
const DEMO_KEYPRESS_BIT_MASK_TABLE = [
  0x00,                          //  0: freefall
  INPUT_ROTATE_RIGHT,            //  1: rotate right
  0x00,                          //  2: nothing
  INPUT_FIRE,                    //  3: fire at turret
  INPUT_ROTATE_LEFT,             //  4: rotate left
  INPUT_SHIELD_TRACTOR,          //  5: shield/tractor
  INPUT_THRUST | INPUT_SHIELD,   //  6: thrust + shield
  // ... 18 entries total
];

// How long (in game ticks) to hold each entry
const demoKeypressTimerTable = [
  0x18,  // 24 ticks of freefall
  0x0F,  // 15 ticks rotate right
  0x05,  //  5 ticks nothing
  0x05,  //  5 ticks fire
  0x08,  //  8 ticks rotate left
  0x14,  // 20 ticks shield/tractor
  0x17,  // 23 ticks thrust + shield
  // ...
];

Three of the timer slots are randomised at the start of each demo run — small variations like (rnd & 0x03) + 0x08 for a range of 8–11 ticks, and a 75/25 split between a long and short spiral at the end. Elegant and simple: it creates just enough variation that repeated attract sequences don't feel mechanical.

Getting it working required understanding yet another layer of timing, and it exposed a small inaccuracy in the player starting position — just enough that the demo sequence missed a turret it should have hit. That led me to discover I'd slightly miscalculated the spawn points, which in turn revealed there were multiple spawn points per level, something I'd overlooked in the initial level decoding.

That this works as it does demonstrates that the physics recreation is accurate - if it wasn't timed keypresses would result in different behaviours and its unlikely the shot would hit the turret and the player escape with the pod.

The Teleport Animation

One moment that impressed me with the coding assistant: the teleport animation — the effect when you warp into a level — wasn't matching the original based on the spec I'd extracted from the disassembly. Rather than spend more time on the code, I recorded the original game as a video, captured the animation frames, pasted them into Claude Code and said "recreate that." It nailed it almost perfectly in about five minutes. Not hard code — something I could have done in half an hour — but a good example of where AI saves time on the uninteresting stuff so you can focus on the interesting stuff.

The CRT Effects

To round things off I added a few CRT post-processing effects: scanlines, green phosphor, amber phosphor, black and white TV, and a VCR look. These are implemented as WebGPU compute shaders in WGSL, falling back gracefully when WebGPU isn't available. Nothing particularly difficult — I pulled most of them from my Elite conversion and added the black and white filter.

I didn't get much time to play the BBC on a colour TV. When I first got one I was playing on a tiny 12-inch black and white set, and later a small green screen monitor. The filters are just a bit of fun, but they do give it an authentic feel.

What This Was Really About

The interesting thing about this process wasn't writing the code. The code is straightforward — by modern standards, a 1986 game that ran in 32K is not particularly complicated. That's not a slight on the original developer and it's amazing that Jeremy Smith got this working on an 8-bit machine, and Exile is something else entirely. But with a high-level language and all the power we have today, the resources online, the coding tools then the implementation is the easy part.

What was interesting was the understanding. Using AI to drill into the original 6502 assembly, to extract and document the subsystems, to understand the specific timings and fixed-point arithmetic and hardware interfaces — that's where the value was. The recreation forced me to understand every system deeply, because getting the feel right meant getting the details right.

AI couldn't recreate Thrust for me — that was proved pretty conclusively in the first five minutes. But it could help me understand the original well enough to recreate it myself.

The source is on GitHub and you can play it here. Going through these codebases from the 8-bit era gives you real respect for the developers. It's amazing what they squeezed into such limited hardware. There's also a YouTube video I created on the process.

I really enjoyed it. I played this game a lot when I was young and it's great to have gained this understanding of how it really works - having done so I appreciate the work Jeremy Smith did even more.

Teaching an LLM to Write Assembly: GBNF-Constrained Generation for a Custom 8-Bit CPU

James Randall — Thu, 04 Dec 2025 08:03:51 +0000

Over the past few weeks I’ve been building a fully-playable 8-bit virtual console from scratch — CPU, instruction set, assembler, sprite system, IDE, the lot. One of the more interesting side quests has been teaching an LLM to generate valid assembly targeting my CPU. You can follow the full build in my YouTube series here. It's called Building a Virtual 8-Bit Console with an AI Assistant and we're up to about part 14 and things are still ongoing. The source code for the project can be found on GitHub here - snapshot at the tag where I added this work.

If you’ve ever tried asking a model to generate domain-specific code, you’ll know what happens: it writes things that look right, but your parser throws it back at you in disgust.

I wanted something different. I needed this to work. I wanted the model to only produce tokens that my assembler would accept.

That led me into the world of GBNF — a compact grammar notation supported by llama.cpp and other inference runtimes, which lets you force the model to emit only syntactically valid output.

In this post I’m going to walk through:

What GBNF actually is
How to design a grammar for an assembly-like DSL
How to plug it into llama.cpp for constrained generation
What worked, what failed, and what surprised me
How it performs when generating real code for a real CPU

And its worth emphasising that this isn’t a theoretical post. It's the exact approach I’m using in my IDE to let developers (or AIs) write programs for the console I’m building.

Even if you're not generating code for a fictional CPU, the principles here apply to any domain where you need guaranteed-valid output: config files, structured data, DSLs, test scripts, game engines, or anything brittle.

Why We Need Grammar-Constrained Generation

LLMs are pattern machines and predictors, not parsers. They’re very good at capturing intent (“draw a sprite at (10,10)”), but surprisingly bad at following the exact syntax rules of a DSL or assembly language — especially a brand-new one they’ve never seen before.

When I first experimented with generating code for my CPU, I tried Qwen locally without any grammar constraints. It was… catastrophic. The model produced:

hallucinated opcodes
invented addressing modes
malformed instructions
missing commas and stray punctuation
registers that don’t exist
syntax that looked plausibly “assembly-ish” but was entirely useless

Claude Sonnet 4.5 did a much better job, and with some prompt tweaking it produced mostly-correct code — but even then it still made small syntactic mistakes that would immediately break the pipeline.

And assembly is brittle:

one stray comma and everything breaks
an unknown opcode and the assembler bails
a missing operand and the whole program collapses

If you simply ask an LLM to “write some assembly,” particularly for an instruction set it cannot have been trained on because you literally just invented it, you get output that looks plausible but fails the moment you feed it into a real assembler.

Grammar-constrained generation changes the game.

Instead of cleaning up a mess afterwards, you make the mess impossible by ensuring the model can only emit legal token sequences. You remove an entire class of errors up front.

You still have to worry about semantics (whether the code actually does the right thing — I’ll cover that in a future post), but at least you’re no longer fighting the syntax.

Yes, what I'm doing here is a slightly off-the-wall demo — generating assembly for a fictional CPU — but the problem generalises. If you’ve ever tried generating anything complex, brittle, and highly specific, you’ve probably hit the same wall. And even if you can coax a bigger model like Claude into doing this cleanly, grammar-constrained generation lets you drop down to smaller, cheaper, local models while still getting reliable, structured output.

What GBNF Is and Why It Works

GBNF is a small grammar format that describes which token sequences are valid in your language. Several inference runtimes (including llama.cpp and vLLM) can use it during decoding to constrain what the model is allowed to output. Its worth pointing out that other runtimes use different approaches but the fundamental approach is the same, its the expression of the grammar that mostly differs.

At a high level:

you describe your language using GBNF: rules, terminals, non-terminals
the runtime loads this grammar
during generation, it masks out any tokens that would violate the grammar
the LLM is effectively forced to walk only along valid paths in your language

This does not magically make the model understand your DSL or, in my case, assembly. It simply means:

if your grammar says opcodes are LOAD | STORE | ADD | SUB,
the model cannot invent LOADX or SUBTRACT or MOVE.

Here's a simplified excerpt from my actual grammar:

root ::= line*
line ::= ws* statement? comment? eol

statement ::= instruction | directive
instruction ::= opcode-noarg
              | opcode-single ws+ operand
              | opcode-double ws+ operand ws* "," ws* operand

opcode-noarg ::= "NOP"i | "RET"i | "RTI"i | "SEI"i | "CLI"i
opcode-single ::= "PUSH"i | "POP"i | "INC"i | "DEC"i | "JMP"i | "CALL"i
opcode-double ::= "LD"i | "ST"i | "MOV"i | "ADD"i | "SUB"i | "AND"i | "OR"i | "XOR"i | "CMP"i

operand ::= immediate | register | memory-ref | identifier
immediate ::= "#" (number | identifier)
register ::= "R"i [0-5] | "SP"i | "PC"i
memory-ref ::= "[" ws* (number | identifier) ws* "]"

number ::= "$" [0-9a-fA-F]+ | [0-9]+
identifier ::= [a-zA-Z_] [a-zA-Z0-9_]*
comment ::= ws* ";" [^\r\n]*
ws ::= [ \t]+
eol ::= "\r"? "\n" | "\r"

The "i" suffix makes matching case-insensitive, so LD, ld, and Ld are all valid. The important part is that the grammar mirrors exactly what my assembler expects to see.

GBNF sits in a sweet spot: simpler than a full PEG/EBNF parser, but expressive enough to model a real assembly language.

Designing a Grammar for a Real Instruction Set

I've been taking a spec first approach to the 8-bit console so I already had comprehensive specifications for the assembler and the CPU. I also had an AI cheatsheet that I'd been feeding to Claude to help it understand the assembler and hardware. And in addition to that I also had a good set of working example code that I'd already written.

And so a great way for me to design the grammar was to start with the things I had.

And what I mean is for me to design the grammar is for me to give the source material to Claude and have it design the grammar and me review it.

The resulting grammar file can be found here.

This came out pretty much spot on first time and I was able to review it line by line and validate it against my examples.

Using GBNF with llama.cpp

Once you have a grammar file, wiring it into llama.cpp is straightforward. The llama.cpp server exposes a /completion endpoint that accepts a grammar parameter containing your GBNF grammar as a string.

Here's the actual TypeScript code I'm using in the IDE:

async generateWithGrammar(prompt: string, grammar: string): Promise<string> {
  const response = await fetch(`${this.codegenUrl}/completion`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      prompt,
      n_predict: 4096,
      grammar,
      temperature: 0.7,
      stop: ['\n\n\n'],
    }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`llama.cpp grammar generation failed: ${response.status} ${errorText}`);
  }

  const result = await response.json();
  return result.content;
}

The key parameters:

prompt — the full prompt including any context and instructions
grammar — the GBNF grammar as a string (I load the file and pass its contents)
n_predict — maximum tokens to generate (4096 gives plenty of room for longer programs)
temperature — I use 0.7 for some creativity while staying coherent
stop — I use triple newlines as a stop sequence to end generation cleanly

The interesting moment is the first time the model produces perfectly valid assembly on the first attempt — because the grammar has done the heavy lifting. After using Qwen without constrained generation and seeing just an absolute mass of errors it was genuinely revelatory to see perfectly valid assembly being generated from the same model.

Where GBNF Helps (and Where It Doesn't)

So while grammar-constrained generation is powerful its imporant to me clear about what it deoesn't buy you.

Where GBNF helps

Syntactic correctness — This is the big one. Every line the model emits will parse. No more LOADX when you only have LD. No more forgetting commas between operands. No more invented addressing modes like [R0+R1] when your CPU doesn't support indexed addressing. The grammar makes these errors structurally impossible. Of course I could have errors in my grammar.... turtles all the way down.

Preventing hallucinated opcodes — Without constraints, models love to invent plausible-sounding instructions. I saw Qwen generate SUBTRACT, MOVE, JUMP, and LOADB — none of which exist in my instruction set. My CPU is 6502 inspired with a RISC twist and I also saw it using 6502 operands like LDA and STX. With the grammar in place, the model can only pick from the opcodes I've explicitly defined: LD, ST, ADD, SUB, and so on.

Proper operand structure — My CPU has specific rules: immediates start with #, memory references use square brackets, hex numbers use $ prefix. The grammar enforces all of this. You can't accidentally write LD R0, 42 when you meant LD R0, #42. Qwen with grammar does a better job than Claude without in this regard, I find Claude trips up over addressing mode structures.

Valid registers and directives — I only have R0 through R5, plus SP and PC. The grammar won't let the model reference R6 or AX or any other register that doesn't exist. Same for assembler directives — only .org, .db, .dw, and the others I've defined.

Consistent formatting — The output follows a predictable structure. Comments always start with ;. Labels always end with :. Whitespace is handled consistently. This might seem minor, but it makes the generated code much easier to read and debug.

Where GBNF doesn't help

Semantic correctness — The grammar ensures you write valid assembly, not correct assembly. If you ask the model to add two numbers and it subtracts them instead, the grammar won't catch that. SUB R0, R1, R2 is perfectly valid syntax even when you wanted ADD.

Algorithmic quality — The model might generate a working sprite-drawing routine that's absurdly inefficient — using a loop where a single instruction would do, or loading the same value from memory repeatedly instead of keeping it in a register. The grammar has no opinion on this.

Efficiency — Related to the above: the model doesn't understand your CPU's pipeline, how many cycles each instruction takes, or what operations are expensive. It might generate code that works but runs slowly. For my virtual console this matters less than for real hardware, but it's still a limitation.

Calling conventions — If your architecture has conventions about which registers are caller-saved versus callee-saved, or how to pass arguments, the grammar won't enforce them. The model might trash R5 in a subroutine without saving it first, breaking code that calls it.

Higher-level logic — The model doesn't actually understand what your program is supposed to do. It's pattern-matching based on your prompt and its training. It might write syntactically perfect assembly that does something completely different from what you asked for.

The bottom line

GBNF is a guardrail, not a full program verifier. It solves the "will this even assemble?" problem completely, which is genuinely valuable — you eliminate an entire class of errors up front. But it leaves the "does this code actually work?" problem entirely to you (or to an agentic feedback loop, which I'll discuss in a later section).

Real Results (What the Model Actually Produced)

Let's look at what the model actually generates. I asked it to write a simple program: clear the screen and draw a red square (16x16) in the center of the screen. This is a good test because it requires understanding the video memory layout, coordinate calculations, and the 4bpp pixel packing format.

Here's the exact output from Qwen with grammar constraints:

; Clear Screen and Draw Red Square Example
; Demonstrates clear screen and pixel drawing subroutine in Video Mode 0 (256x160 @ 4bpp)
;
; Subroutine: draw_pixel
;   Inputs: R0 = X coordinate, R1 = Y coordinate, R2 = color (palette index)
;   Draws a single pixel at (X,Y) with the specified color

.org $0B80

; Constants
.define VIDEO_MODE $0101
.define PALETTE_RAM $0200
.define FRAMEBUFFER_START $B000

; Entry point
main:
    ; Set video mode to 0 (256x160 @ 4bpp)
    LD R0, #0
    ST R0, [VIDEO_MODE]

    ; Clear screen to black (color 0)
    CALL clear_screen

    ; Draw 16x16 red square at the center (X=112, Y=72)
    LD R2, #2          ; Color 2 (red)
    LD R1, #72
    LD R3, #16         ; Loop counter for y-axis
.y_loop:
    LD R0, #112        ; X = 112
    LD R4, #16         ; Loop counter for x-axis
.x_loop:
    CALL draw_pixel
    INC R0
    DEC R4
    BRNZ .x_loop
    INC R1
    DEC R3
    BRNZ .y_loop

    ; Infinite loop - program done
done:
    JMP done

; Subroutine: Clear screen to color 0
; Uses register pairs to iterate through framebuffer
clear_screen:
    PUSH R0
    PUSH R2
    PUSH R3
    PUSH R4

    ; R2:R3 will be the address pointer
    LD R2, #$B0        ; High byte of framebuffer start
    LD R3, #$00        ; Low byte
    LD R4, #$50        ; 80 pages (0x5000 bytes = 20480 bytes for mode 0)
    LD R0, #0          ; Color to write (0 = black)

.outer:
.inner:
    ST R0, [R2:R3]     ; Write byte at R2:R3
    INC R3             ; Increment low byte
    BRNZ .inner        ; Loop until R3 wraps to 0

    INC R2             ; Increment high byte (next page)
    DEC R4             ; Decrement page counter
    BRNZ .outer        ; Loop until all pages done

    POP R4
    POP R3
    POP R2
    POP R0
    RET

; Subroutine: Draw pixel at (X, Y) with color
; Inputs: R0 = X coordinate (0-255)
;         R1 = Y coordinate (0-159)
;         R2 = color (palette index 0-15)
;
; Mode 0 is 4bpp, so 2 pixels per byte:
;   - Even X: high nibble
;   - Odd X: low nibble
; Address calculation: 0xB000 + (Y * 128) + (X / 2)
draw_pixel:
    PUSH R0
    PUSH R1
    PUSH R2
    PUSH R3
    PUSH R4
    PUSH R5

    ; Bounds check Y
    CMP R1, #160
    BRC .exit          ; Exit if Y >= 160

    ; Calculate address: 0xB000 + (Y * 128) + (X / 2)
    ; Y * 128 = Y << 7
    ; We'll use R3:R4 as a 16-bit value for the address offset

    LD R3, #0          ; R3 = high byte of offset (initially 0)
    MOV R4, R1         ; R4 = low byte (Y value)

    ; Shift R3:R4 left by 7 positions (multiply Y by 128)
    SHL R4
    ROL R3
    SHL R4
    ROL R3
    SHL R4
    ROL R3
    SHL R4
    ROL R3
    SHL R4
    ROL R3
    SHL R4
    ROL R3
    SHL R4
    ROL R3

    ; Add X/2 to the low byte
    MOV R5, R0         ; Copy X to R5
    SHR R5             ; R5 = X / 2
    ADD R4, R5         ; Add to low byte
    BRC .carry         ; Check for carry
    JMP .no_carry

.carry:
    INC R3             ; Propagate carry to high byte

.no_carry:
    ; Add framebuffer base address (0xB000) to high byte
    ADD R3, #$B0

    ; Now R3:R4 contains the final address
    ; Load the current byte at this address
    LD R5, [R3:R4]

    ; Check if X is even or odd
    AND R0, #1         ; R0 = X & 1 (0 if even, 1 if odd)
    BRNZ .odd_pixel

    ; Even pixel: modify high nibble
    AND R5, #$0F       ; Clear high nibble, keep low nibble
    SHL R2, #4         ; Shift color to high nibble
    OR R5, R2          ; Combine
    JMP .write_byte

.odd_pixel:
    ; Odd pixel: modify low nibble
    AND R5, #$F0       ; Clear low nibble, keep high nibble
    AND R2, #$0F       ; Ensure color is only in low nibble
    OR R5, R2          ; Combine

.write_byte:
    ; Write the modified byte back
    ST R5, [R3:R4]

.exit:
    POP R5
    POP R4
    POP R3
    POP R2
    POP R1
    POP R0
    RET

What the model got right

Perfect syntax — Every single line assembles without error. The grammar did its job: no hallucinated opcodes, no malformed operands, no missing commas. This is the same model that was generating SUBTRACT and LDA before I added constraints. I'm actually yet to see any assembly syntax errors.

Sensible structure — The code follows good assembly conventions: constants defined at the top, a clear entry point, subroutine with proper prologue/epilogue (push/pop all used registers), comments explaining the logic.

Correct algorithm — The pixel-drawing logic is actually sound. It correctly calculates the framebuffer address using Y * 128 + X / 2, handles the 4bpp packing (even pixels in high nibble, odd in low), and preserves the other pixel in the byte when writing.

Hardware-aware — The model understood that my console uses memory-mapped video at $B000, that mode 0 is 256x160 at 4 bits per pixel, and that the palette index for red is 2. All of this came from the context I provided in the prompt which includes the AI cheatsheet I shared earlier.

What surprised me

Color selection — I didn't expect it to find the red color. The system uses custom palettes and although their is a default I'm surprised it found this. Possibly from an example. Or possibly chance!

Screen clearing (or not) - If I generate the code multiple times sometimes it will include code for clearing the screen and sometimes not. If I ask it to add screen clearing code it successfully does so.

Did it actually work?

Yes. I loaded this into the console's IDE, assembled it, and ran it. Or rather my agentic chat assistant did all that for me. A red pixel appeared at (128, 80) — dead center of the screen. No modifications required. When I added screen clearing this worked too.

This is the thing that still surprises me: a (comparatively) small model running locally, with the right constraints and context, can generate working assembly for a CPU that didn't exist until I built it.

Next Steps: Combining GBNF with Agentic Behaviours

I've not really covered this here but I've already combined this model with agentic behaviour in my consoles IDE that can:

Assemble and check for errors (not yet had any of those!)
Access a library of example programs
Run the assembled program
Pause the CPU and inspect the registers and memory
Capture a screenshot and inspect it

The agent is exposed through a chat interface. Oddly enough I don't want the chat talking to me in opcodes so we don't use the grammar unless we're doing code generation. Because I'm running this locally I'm also using different models for chat and code generation. The code generation model has a bigger context window as I need to pass it the cheat sheet and other materials describing the surrounding hardware

The library of example programs has proven essential in the ability of the LLM to generate useful assembly code. I see it both copying subsections of the examples in verbatim and also essentially creating derived works.

Combined with the agentic tools the constrained generation starts to feel like a real assistant rather than a suggestion generator.

Closing

GBNF doesn’t make an LLM understand your language — but it forces it to follow the rules. For a custom 8-bit console, that’s exactly what you need. And if you're working with agentic system that need to generate precise outputs it probably is what you need too.

It’s a satisfying intersection of old-school compiler techniques and modern LLM tooling.

C# / Blazor Wolfenstein - Part 1 - Blazor

James Randall — Fri, 11 Nov 2022 07:44:15 +0000

I thought it might be fun to convert my F# version of Wolfenstein 3D (code here, playable in the browser here) to use modern C# and use Blazor to run it in the browser hopefully ending up with something like this below (screenshot grabbed in Edge on a Mac):

I've often been asked to document my work on these fun projects and so here's part 1. There's not much there yet as today was a "voyage of discovery" to figure out how to handle the basics of rendering with a byte array - Wolfenstein 3D, and my F# version, are raycasters that essentially work with the individual pixels rather than using hardware acceleration and I needed an approach that would work with Blazor from WASM land.

My initial attempt at this was to use the Blazor.Extensions.Canvas package to do this much the same way I had with F# - I expected their might be excessive interop cost around putImageData (how you update the underlying data) but it seemed a good place to start. Unfortunately the authors of that package have not exposed that method so that quickly stymied that.

Attempt two was to use the WebGL context on the canvas to pretty much do the same. Write to a byte array, load that up as a texture, and then render and texture map the image onto a rectangular surface. That approach was also stymied as the somewhat critical texImage2D method doesn't work. The C# version is bound incorrectly to JS and the package hasn't been updated for a good while.

Which brings me to a massive bugbear I have with Blazor - Microsoft seemed to have shrugged their shoulders when it comes to providing access to browser APIs. Literally living in their own little world and relying on "the community" (i.e. free labour) to plug the gaps. Its ludicrous. If you're going to implement a browser framework in WASM you have, have, have to provide access to the browser APIs or people are just going to run into surprising and unexpected roadblocks. To me that seems like table stakes.

I nearly stopped at this point thinking oh well I'll just do it on the desktop using OpenGL like the F# desktop version. This is supposed to be fun and not teeth pulling after all. Then I remembered SkiaSharp - turns out some brave soul has got that working with Blazor and WebAssembly and had another go.

After a bit of experimenting with what would be the most optimal way of rendering essentially a byte array of pixels I found a method that worked acceptably and, well, here we are. End of part 1 - I have some scrappy code that can render a byte array to a canvas element in the browser and you can find the source for this part here and an exciting screenshot of this below:

We're not quite at the "wow it looks like Wolfenstein" stage just yet.

The key piece of code to getting this performant, which I can take no credit for - SkiaSharp has excellent documentation, is this:

unsafe
{
    fixed (uint* ptr = _renderer.UpdateFrameBuffer())
    {
        _bitmap.SetPixels((IntPtr)ptr);
    }
}
canvas.DrawBitmap(_bitmap, new SKRect(0, 0, WolfViewportWidth*CanvasZoom, WolfViewportHeight*CanvasZoom));

This basically allows my renderer to work in an abstract manner on an array of bytes (well uint's actually but we'll come back to that) and then create an SKBitmap from them and draw that onto the canvas. Interestingly using a 2D canvas was much faster than a WebGL canvas - I assume because with the latter somewhere or other with the dynamic nature of my texture I'm incurring yet another JS interop hop with a large array.

Back to the array. Why a uint and not a byte array? Each pixel is made up of a red, green, blue and alpha component with each component being a byte long. Using a uint simply allows me to treat a pixel as an element in the array rather than grappling with 4 elements per pixel. Shorthand really and you end up with something a bit like this:

public uint[,] UpdateFrameBuffer()
{
    for (int row = 0; row < _height; row++)
    {
        for (int col = 0; col < _width; col++)
        {
            _buffer[row, col] = MakePixel((byte) col, 0, (byte) row, 0xFF);
        }
    }
    return _buffer;
}

What I'll be doing now is walking towards replacing that simple placeholder with, well, Wolfenstein. Next step will be loading the maps and graphics.

And an aside: was quite impressed to find that unsafe code is supported in the .NET WASM compiler. I mean there's no reason it shouldn't be but it had the feel of one of those things I was going to try and get an unpleasant error message back from.

Going forwards my plan is to do this in a fairly functional style - probably go back and forth a bit as I've not written much C# for a couple of language versions. I had some more functional stuff in the WebGL version (stupidly deleted) and my thoughts so far are that its a bit weird. Having records but not free standing functions is just very strange to an F#er, and good lord their is so very much typing even with Rider / Intellisense / CoPilot.

Hopefully once I've wrapped my head around current C# the code will end up more elegant than my F# version - after all in that version I was grappling with how to build a raycaster and how to make it play like Wolfenstein. This time they are both solved problems.

Elegant Azure Functions Development in C# with Function Monkey

James Randall — Mon, 16 Sep 2019 09:50:49 +0000

This article is part of #ServerlessSeptember. You'll find other helpful articles, detailed tutorials, and videos in this all-things-Serverless content collection. New articles are published every day — that's right, every day — from community members and cloud advocates in the month of September.

Find out more about how Microsoft Azure enables your Serverless functions at https://docs.microsoft.com/azure/azure-functions/.

The managed environment, consumption based billing and the event based programming model of Azure Functions makes them an ideal compute platform for many cloud applications and the simplicity can make it super easy to get started and try out ideas. However without care its easy for a codebase to grow to contain a lot of repetitive boilerplate and inconsistencies. Additionally the fairly raw nature of HTTP functions can make it difficult to build a REST API as you need to provide a lot of the plumbing you'd get for free with something like ASP.Net Core (a much requested feature for Azure Functions is to be able to run ASP.Net Core - I'm sure it will arrive eventually but its not here yet!).

Many examples of Azure Functions focus on simple use cases and don't really address these things. As such you'll often see the trigger, logging, serialization and other cross cutting concerns wrapped up with the business problem and it all gets a bit messy. While this can be fine for small projects it can become a maintenance nightmare when you have more than a handful of functions, limits reuse and can make it difficult to host your business logic in different environments.

To address this I created Function Monkey - a framework that allows you to write Azure Functions using the command and mediator pattern in a way that naturally leads to a clean separation of concerns and also provides the infrastructure for building REST APIs and uses a declarative builder style approach to creating a serverless application based on Azure Functions.

To demonstrate how this works I'm going to show how you can use Function Monkey to build out the backend for a simple ToDo application in C# that makes use of Cosmos DB as a data store and then show how the command dispatcher / mediator can be used to address additional cross cutting concerns.

There's a lot of code in this post and the code for the completed project can be found on GitHub.

Creating a REST API

Firstly, using the IDE or editor of your choice (I use Rider), create an empty Azure Functions application and then install two NuGet packages:

dotnet add package FunctionMonkey -v 3.0.11-beta5
dotnet add package FunctionMonkey.Compiler -v 3.0.12-beta5

Note: we're adding beta versions of Function Monkey here and so if you're using an IDE you may need to enable pre-release packages - one of the additions to the 3.x series was support for Service Bus sessions however that requires referencing a beta version of the Microsoft.Azure.WebJobs.Extensions.ServiceBus package, the Function Monkey packages will be moved out of preview just as soon as that is but in all other respects they are production ready.

We'll begin by create a model to represent a ToDo item. Create a folder in the project called Models and in that folder create a class called ToDoItem:

using System;

namespace ToDo.Models
{
    public class ToDoItem
    {
        public string Id { get; set; }

        public string CreatedByUserId { get; set; }

        public string Title { get; set; }

        public DateTime CreatedAtUtc { get; set; }

        public bool IsComplete { get; set; }
    }
}

Next create a folder in the project called Commands and in that folder create a class called AddToDoItem that contains the state needed to create a command for a given user:

using System;
using AzureFromTheTrenches.Commanding.Abstractions;
using ToDo.Models;

namespace ToDo.Commands
{
    public class AddToDoItemCommand : ICommand<ToDoItem>
    {
        public string UserId { get; set; }

        public string Title { get; set; }
    }
}

ICommand is a Function Monkey defined interface that identifies a class as being a command, in this case we also declare a response type for the command and set it to be our ToDoItem model - we'll return the newly created item. If your command does not have a response then their is a non-generic variant that can be used to declare a command with no response.

Now we have a mechanism of representing a ToDo item and a means of expressing our intent to create an item we need to implement the functionality that will carry this out. First create a folder called Services and in their create an interface called IToDoItemRepository:

using System;
using System.Threading.Tasks;
using ToDo.Models;

namespace ToDo.Services
{
    internal interface IToDoItemRepository
    {
        Task Upsert(ToDoItem toDoItem);
    }
}

We'll use Azure Cosmos DB as our database for this simple application and so before we can fill out the implementation of our repository we'll need to add the Cosmos DB package:

dotnet add package FunctionMonkey Microsoft.Azure.Cosmos

This will add the latest 3.x version of the Cosmos client which is a big improvement on previous releases with many usability and performance enhance,ments.

You'll need to create a Cosmos account and inside that a database and a document container, if you're new to Cosmos you can follow these instructions. As you create the resources take note of the Cosmos connection string, the database name and the container name as we'll need them in the next steps.

Now we'll need a way of getting the connection information for Cosmos to our repository. To do this we'll create a class called ApplicationSettings in the root of our project:

namespace ToDo
{
    internal class ApplicationSettings
    {
        public string CosmosConnectionString { get; set; }

        public string CosmosDatabaseName { get; set; }

        public string CosmosContainerName { get; set; }
    }
}

And now we can create an implementation of our repository interface in the Services folder called ToDoItemRepository:

using System;
using System.Collections.Concurrent;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;
using ToDo.Models;

namespace ToDo.Services
{
    internal class ToDoItemRepository : IToDoItemRepository
    {
        private readonly CosmosClient _cosmosClient;
        private readonly string _databaseName;
        private readonly string _containerName;

        public ToDoItemRepository(ApplicationSettings settings)
        {
            CosmosClientOptions options = new CosmosClientOptions()
            {
                SerializerOptions = new CosmosSerializationOptions()
                {
                    PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
                }
            };
            _cosmosClient = new CosmosClient(settings.CosmosConnectionString, options);
            _databaseName = settings.CosmosDatabaseName;
            _containerName = settings.CosmosContainerName;
        }

        public async Task Upsert(ToDoItem toDoItem)
        {
            Container container = _cosmosClient.GetContainer(_databaseName, _containerName);
            await container.UpsertItemAsync(toDoItem, new PartitionKey(toDoItem.Id));
        }
    }
}

In the sample above we're using a feature of the new 3.x Cosmos client to use camel case when serializing our models - previously we would have needed to mark our Id property on the ToDoItem class with JsonProperty("id") or use lower case for its name. In our upsert method we simply use the client to upsert a to do item.

Next we need to wire all this up with a command handler. Create a folder called Handlers and create a class called AddToDoItemCommandHandler:

using System;
using System.Threading.Tasks;
using AzureFromTheTrenches.Commanding.Abstractions;
using ToDo.Commands;
using ToDo.Models;
using ToDo.Services;

namespace ToDo.Handlers
{
    internal class AddToDoItemCommandHandler : ICommandHandler<AddToDoItemCommand, ToDoItem>
    {
        private readonly IToDoItemRepository _repository;

        public AddToDoItemCommandHandler(IToDoItemRepository repository)
        {
            _repository = repository;
        }

        public async Task<ToDoItem> ExecuteAsync(AddToDoItemCommand command, ToDoItem previousResult)
        {
            ToDoItem newItem = new ToDoItem
            {
                CreatedAtUtc = DateTime.UtcNow,
                CreatedByUserId = command.UserId,
                Id = Guid.NewGuid().ToString(),
                IsComplete = false,
                Title = command.Title
            };
            await _repository.Upsert(newItem);
            return newItem;
        }
    }
}

Command handlers are marked by their implementation of the ICommandHandler interface which accepts as its first generic parameter the type of the command it responds to and as the second, optional, generic parameter the response type of the command. Handlers must then implement the ExecuteAsync method to perform their logic. Although we won't use the functionality in this walk-through multiple command handlers can run in response to a command and the previousResult parameter represents the output from the previous handler. In our case it will always be null.

Finally with our command, command handler and repository in place we can wire it all together and expose out add command as a function by providing a function app builder. To do this create a class called FunctionAppConfiguration in the project root that implements the IFunctionAppConfiguration interface as shown below:

using System;
using System.Net.Http;
using FunctionMonkey.Abstractions;
using FunctionMonkey.Abstractions.Builders;
using Microsoft.Extensions.DependencyInjection;
using ToDo.Commands;
using ToDo.Services;

namespace ToDo
{
    public class FunctionAppConfiguration : IFunctionAppConfiguration
    {
        public void Build(IFunctionHostBuilder builder)
        {
            builder
                .Setup((serviceCollection, commandRegistry) =>
                {
                    ApplicationSettings applicationSettings = new ApplicationSettings
                    {
                         CosmosContainerName = "todoItems",
                         CosmosDatabaseName = "testdatabase",
                         CosmosConnectionString = 
                             Environment.GetEnvironmentVariable("cosmosConnectionString", EnvironmentVariableTarget.Process)
                    };
                    serviceCollection
                        .AddSingleton(applicationSettings)
                        .AddTransient<IToDoItemRepository, ToDoItemRepository>();
                    commandRegistry.Discover<FunctionAppConfiguration>();
                })
                .Functions(functions => functions
                    .HttpRoute("api/v1/todoItem", route => route
                        .HttpFunction<AddToDoItemCommand>(HttpMethod.Post)
                    )
                );
        }
    }
}

The Setup method exposes an IServiceCollection interface for us to register our dependencies - in this case we register the repository (required by the handler) and the application settings (required by the repository). It also exposes an ICommandRegistry interface for us to register our commands and handlers. We can do this manually or, more straightforwardly, by using the Discover method and providing a generic argument of a type in the assembly that contains the handlers.

Next the Functions method allows us to register our functions. In this case we declare a HTTP route and a function on that route that binds the post verb to the AddToDoItemCommand.

Before we can run this we have just two final changes to make. First (for reasons that will become more obvious a little later) we need to prevent Azure Functions from prefixing "api" onto each of our functions. We do this by creating a host.json file with the following contents:

{
    "version": "2.0",
    "extensions": {
        "http": {
            "routePrefix": ""
        }
    }
}

And finally we need to provide the connection information for Cosmos, as we're going to be running these functions locally we'll set this up in our local.settings.json file:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "cosmosConnectionString": "<enter your connection string here>"
    }
}

Azure Functions need a storage account to run and in this example I've used the storage emulator. If you're running on a Mac you can use a real storage account or use Azurite (an open source alternative to the Azure Storage Emulator).

With all that done we can, finally!, run our Azure Functions app. If we run the app we can make a request in Postman to our endpoint and see the created ToDo item returned:

Great - we can call our endpoint using the POST verb and have a to do item created, saved in Cosmos, and returned. However if you look at the payload we passed to Postman you might notice we're passing in a user ID. This is intended to be the ID of the user who is signed in but being able to pass it as part of the payload would mean any authentication and authorisation system could be circumvented. To address this we'll set Function Monkey up so it reads the user ID from a claim. In a real example we'd use a signed token in the Authorization header but to demonstrate how this works we'll simply validate that a token is supplied and set things up with a hard coded user ID. If you're interested in exploring this more fully see this video which demonstrates how to configure authorization against Auth0.

First we need to implement a class that can validate a supplied token - we do this by implementing the ITokenValidator interface. Add the class TokenValidator to the root of the project:

using System.Security.Claims;
using System.Threading.Tasks;
using FunctionMonkey.Abstractions;

namespace ToDo
{
    public class TokenValidator : ITokenValidator
    {
        public Task<ClaimsPrincipal> ValidateAsync(string authorizationHeader)
        {
            if (string.IsNullOrEmpty(authorizationHeader))
            {
                return Task.FromResult<ClaimsPrincipal>(null);
            }

            ClaimsPrincipal claimsPrincipal = new ClaimsPrincipal(
                new[]
                {
                    new ClaimsIdentity(new[]
                    {
                        new Claim("userId", "user1"),
                    }),
                }
            );
            return Task.FromResult(claimsPrincipal);
        }
    }
}

For authorized users token validators should return a ClaimsPrincipal (normally constructed from the claims in a bearer token - see the documentation here) or return null (or throw an exception) for unauthorized users. In this example we create a claim with a name of userId and give it a hardcoded value of user1 if any none-zero length value is passed in the Authorization header.

Now we need to tell Function Monkey to use this validator and to map the claim on to the UserId property of our command. We do this using the Authorization builder options as shown below:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup( /* as before */ )
        .Authorization(authorization => authorization
            .TokenValidator<TokenValidator>()
            .AuthorizationDefault(AuthorizationTypeEnum.TokenValidation)
            .Claims(claims => claims
                .MapClaimToCommandProperty<AddToDoItemCommand>("userId", cmd => cmd.UserId)
            )
        )
        .Functions( /* as before */ );
}

We're doing three things here:

We use the TokenValidator<> method to register our token validator implementation as the one Function Monkey should use.
We use the AuthorizationDefault method to tell Function Monkey that the default authorization mode for all our functions is token validation
We use the Claims method and the MapClaimToCommandProperty method to tell Function Monkey to set the UserId property on the AddToDoItemCommand from the name identifier claim in our claims principal.

With that done we have one more thing to do - we need to tell Function Monkey to never allow our UserId property to be set by anything other than a claims mapping - that way no one can use a request body or query, header, or route parameters to set the user ID. We do that by marking it with the SecurityProperty attribute on the command model:

public class AddToDoItemCommand : ICommand<ToDoItem>
{
    [SecurityProperty]
    public string UserId { get; set; }

    public string Title { get; set; }
}

With that done lets try making a POST request in Postman. When we do so without setting an authorization header we get a 401 Unauthorized error as shown below:

But if we set an Authorization header the request is successful and the user ID of the created post is set to user1 - the value we set in our claims principal:

Next lets add some validation to our inputs. Function Monkey supports validation of commands by any validation framework of your choice but includes a package for easy use of Fluent Validation. First we'll need to add the package:

dotnet add package FunctionMonkey.FluentValidation -v 3.0.11-beta5

Next create a folder called Validators and in there create a class called AddToDoItemCommandValidator:

using FluentValidation;
using ToDo.Commands;

namespace ToDo.Validators
{
    public class AddToDoItemCommandValidator : AbstractValidator<AddToDoItemCommand>
    {
        public AddToDoItemCommandValidator()
        {
            RuleFor(x => x.UserId).NotEmpty();
            RuleFor(x => x.Title).NotEmpty().MaximumLength(128);
        }
    }
}

The above is just standard Fluent Validation code. Note that we can validate the UserId because validation takes place after claims mapping has occurred. We now need to register our validator in our builder and we can do this in a similar way to how we added our commands and handlers:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup((serviceCollection, commandRegistry) =>
        {
            ApplicationSettings applicationSettings = new ApplicationSettings
            {
                 CosmosContainerName = "todoItems",
                 CosmosDatabaseName = "testdatabase",
                 CosmosConnectionString = 
                     Environment.GetEnvironmentVariable("cosmosConnectionString", EnvironmentVariableTarget.Process)
            };
            serviceCollection
                .AddSingleton(applicationSettings)
                .AddTransient<IToDoItemRepository, ToDoItemRepository>()
                .AddValidatorsFromAssemblyContaining<FunctionAppConfiguration>() // add this line
                ;
            commandRegistry.Discover<FunctionAppConfiguration>();
        })
        .AddFluentValidation() // add this line
        .Authorization( /* as before */ )
        .Functions( /* as before */ );
}

If we run this and use Postman to send a post request with an invalid zero length title we can see a bad request response returned:

With all that up and running lets add a new command, or rather a query, that allows us to return all the posts for a given user. Again we begin by creating a class to represent our intent - in the Commands folder create the class GetAllToDoItemsQuery:

using System.Collections.Generic;
using AzureFromTheTrenches.Commanding.Abstractions;
using ToDo.Models;

namespace ToDo.Commands
{
    public class GetAllToDoItemsQuery : ICommand<IReadOnlyCollection<ToDoItem>>
    {
        [SecurityProperty]
        public string UserId { get; set; }
    }
}

You'll notice that we've marked our UserId property as a security property as before however we don't have a claims mapping for this command. We could add a claims mapping for each command type but this could be difficult to maintain with a large number of commands. Instead we'll update our claims mapping to use a convention based approach so that any property on any command called UserId is populated from the userId claim. This requires a small change to our builder:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup( /* as before */ )
        .AddFluentValidation() // as before
        .Authorization(authorization => authorization
            .TokenValidator<TokenValidator>()
            .AuthorizationDefault(AuthorizationTypeEnum.TokenValidation)
            .Claims(claims => claims
                .MapClaimToPropertyName("userId", "UserId") // our change!
            )
        )
        .Functions( /* as before */ );
}

Now we need to add a method to our repositories interface:

internal interface IToDoItemRepository
{
    Task Upsert(ToDoItem toDoItem);

    Task<IReadOnlyCollection<ToDoItem>> Get(Guid userId);
}

And to the implementation:

internal class ToDoItemRepository : IToDoItemRepository
{
    private readonly CosmosClient _cosmosClient;
    private readonly string _databaseName;
    private readonly string _containerName;

    public ToDoItemRepository(ApplicationSettings settings) { /* as before */ }

    public async Task Upsert(ToDoItem toDoItem) { /* as before */ }

    public async Task<IReadOnlyCollection<ToDoItem>> Get(string userId)
    {
        string query = "SELECT * FROM c WHERE c.createdByUserId = @userId";
        Container container = _cosmosClient.GetContainer(_databaseName, _containerName);
        QueryDefinition queryDefinition = new QueryDefinition(query)
            .WithParameter("@userId", userId);
        FeedIterator<ToDoItem> queryResultSetIterator = container.GetItemQueryIterator<ToDoItem>(queryDefinition);

        List<ToDoItem> items = new List<ToDoItem>();
        while (queryResultSetIterator.HasMoreResults)
        {
            FeedResponse<ToDoItem> currentResultSet = await queryResultSetIterator.ReadNextAsync();
            items.AddRange(currentResultSet);
        }

        return items;
    }
}

Next we need a command handler:

using System.Collections.Generic;
using System.Threading.Tasks;
using AzureFromTheTrenches.Commanding.Abstractions;
using ToDo.Commands;
using ToDo.Models;
using ToDo.Services;

namespace ToDo.Handlers
{
    internal class GetAllToDoItemsQueryHandler : ICommandHandler<GetAllToDoItemsQuery, IReadOnlyCollection<ToDoItem>>
    {
        private readonly IToDoItemRepository _repository;

        public GetAllToDoItemsQueryHandler(IToDoItemRepository repository)
        {
            _repository = repository;
        }

        public async Task<IReadOnlyCollection<ToDoItem>> ExecuteAsync(
            GetAllToDoItemsQuery command,
            IReadOnlyCollection<ToDoItem> previousResult)
        {
            return await _repository.Get(command.UserId);
        }
    }
}

And then we need to register our command with a function using our builder:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup( /* unchanged */ )
        .Authorization( /* unchanged */ )
        .Functions(functions => functions
            .HttpRoute("api/v1/todoItem", route => route
                .HttpFunction<AddToDoItemCommand>(HttpMethod.Post)
                .HttpFunction<GetAllToDoItemsQuery>(HttpMethod.Get) // our addition
            )
        );
}

If we run our application and use Postman to call our endpoint we'll see an array of the items we've added so far returned:

Let's wrap up the API by adding a function that allows items to be marked as complete, again we'll need to add a command:

using AzureFromTheTrenches.Commanding.Abstractions;

namespace ToDo.Commands
{
    public class MarkItemCompleteCommand : ICommand
    {
        public string UserId { get; set; }

        public string ItemId { get; set; }
    }
}

We'll need to add a method to our repository to get a single item by id (I'll leave out the interface addition as it should be self explanatory):

public async Task<ToDoItem> GetSingleItem(string itemId)
{
    Container container = _cosmosClient.GetContainer(_databaseName, _containerName);
    return await container.ReadItemAsync<ToDoItem>(itemId, new PartitionKey(itemId));
}

And we'll need a command handler:

using System.Threading.Tasks;
using AzureFromTheTrenches.Commanding.Abstractions;
using ToDo.Commands;
using ToDo.Models;
using ToDo.Services;

namespace ToDo.Handlers
{
    internal class MarkItemCompleteCommandHandler : ICommandHandler<MarkItemCompleteCommand>
    {
        private readonly IToDoItemRepository _repository;

        public MarkItemCompleteCommandHandler(IToDoItemRepository repository)
        {
            _repository = repository;
        }

        public async Task ExecuteAsync(MarkItemCompleteCommand command)
        {
            ToDoItem item = await _repository.GetSingleItem(command.ItemId);
            item.IsComplete = true;
            await _repository.Upsert(item);
        }
    }
}

And finally we'll need to map the command to a function. We'll use the PUT verb and supply the item ID using a route parameter:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup((serviceCollection, commandRegistry) => { /* as before */ }
        .AddFluentValidation() /* as before */
        .Authorization( /* as before */ )
        .Functions(functions => functions
            .HttpRoute("api/v1/todoItem", route => route
                .HttpFunction<AddToDoItemCommand>(HttpMethod.Post)
                .HttpFunction<GetAllToDoItemsQuery>(HttpMethod.Get)
                // our addition
                .HttpFunction<MarkItemCompleteCommand>("/{itemId}/complete", HttpMethod.Put)
            )
        );
}

If we run this in Postman we'll get a simple 200 response:

If we look at our MarkItemCompleteCommandHandler we can see that it's possible for a user to change another users item completion status if they know the ID of a to do item. As a final change to the API we'll look at how we can prevent this and return a 401 Unauthorized response using a HTTP response handler. First lets create an exception that we'll throw in this situation:

using System;

namespace ToDo
{
    public class UnauthorizedItemAccessException : Exception
    {

    }
}

Next we'll update our command handler to throw this exception if the user ID on the command doesn't match the user ID of the to do Item:

public async Task ExecuteAsync(MarkItemCompleteCommand command)
{
    ToDoItem item = await _repository.GetSingleItem(command.ItemId);
    if (item.CreatedByUserId != command.UserId)
    {
        throw new UnauthorizedItemAccessException();
    }
    item.IsComplete = true;
    await _repository.Upsert(item);
}

Finally we need a way of translating our .NET exception into a 401 HTTP response. Function Monkey allows you to register a HTTP response handler that can be used to shape responses. Create a class in the root called HttpResponseHandler that implements the IHttpResponseHandler interface:

using System;
using System.Threading.Tasks;
using AzureFromTheTrenches.Commanding;
using AzureFromTheTrenches.Commanding.Abstractions;
using FunctionMonkey.Abstractions.Http;
using FunctionMonkey.Commanding.Abstractions.Validation;
using Microsoft.AspNetCore.Mvc;

namespace ToDo
{
    public class HttpResponseHandler : IHttpResponseHandler
    {
        public Task<IActionResult> CreateResponseFromException<TCommand>(TCommand command, Exception ex) where TCommand : ICommand
        {
            // exceptions thrown from inside command handlers are reraised as CommandExecutionException's with the
            // inner exception set to the handler raised exception - so we need to unwrap this to shape our response
            Exception unwrappedException = ex is CommandExecutionException ? ex.InnerException : ex;
            if (unwrappedException is UnauthorizedAccessException)
            {
                return Task.FromResult((IActionResult) new UnauthorizedResult());
            }

            // returning null tells Function Monkey to create its standard response
            return null;
        }

        public Task<IActionResult> CreateResponse<TCommand, TResult>(TCommand command, TResult result) where TCommand : ICommand<TResult>
        {
            return null; // returning null tells Function Monkey to create its standard response
        }

        public Task<IActionResult> CreateResponse<TCommand>(TCommand command)
        {
            return null; // returning null tells Function Monkey to create its standard response
        }

        public Task<IActionResult> CreateValidationFailureResponse<TCommand>(TCommand command, ValidationResult validationResult) where TCommand : ICommand
        {
            return null; // returning null tells Function Monkey to create its standard response
        }
    }
}

In the above code we simply look for our exception and translate it to the appropriate response. Now we need to update our builder to register it:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup((serviceCollection, commandRegistry) => { /* as before */ }
        .AddFluentValidation() // as before
        .Authorization(/* as before */ )
        .DefaultHttpResponseHandler<HttpResponseHandler>() // added
        .Functions(/* as before */);
}

This is a little difficult to test with our mocked up authorization handler but you can do so by changing the user ID we set in our TokenValidator and attempting to mark an item we created earlier as complete. If you do so you will recieve a 401 Unauthorized in Postman.

Finally lets add Open API support. To do this all we need to do is add a new section to the builder:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup((serviceCollection, commandRegistry) => { /* as before */ }
        .AddFluentValidation() // as before
        .Authorization(/* as before */ )
        .DefaultHttpResponseHandler<HttpResponseHandler>() // as before
        .OpenApiEndpoint(openApi => openApi
            .Title("ToDo API")
            .Version("1.0.0")
            .UserInterface()
        )
        .Functions(/* as before */);
}

With this section added if we run our project and visit http://localhost:7071/openapi we will find the OpenAPI explorer for our project:

It's worth noting that if we hadn't customised our route prefix in the host.json file earlier we wouldn't have been able to place this on the root - instead it would have sat under http://localhost:7071/api/openapi (if you want this behaviour you can simply leave out the host.json routePrefix customisation).

Addressing cross cutting concerns with a custom dispatcher

We've not really seen this in our work so far but Function Monkey makes use of a commanding / mediator framework to associate commands with handlers. When an event occurs the following occurs:

The Azure Functions runtime invokes the appropriate trigger
The trigger is handled by a Function Monkey generated function
The function deserializes the input to the function
The function passes the deserialized input to the dispatcher
The dispatcher locates the handler(s) to invoke
The dispatcher instantiates and executes the handler

The common element to every execution is the dispatcher and we can add behaviour to this to address cross cutting concerns. Examples might include fine grained permissions, logging and telemetry. As an example we'll implement a dispatcher that uses a stopwatch to measure the duration of handler executions and saves them to Azure Application Insights.

To begin with create an Application Insights instance in Azure following these instructions taking note of the instrumentation key. Before you deploy an Azure Functions application into Azure itself its worth also familiarising yourself with the integration between Functions and App Insights.

Next update the local.settings.json file with the instrumentation key:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "cosmosConnectionString": "<enter your connection string here>",
        "APPINSIGHTS_INSTRUMENTATIONKEY": "<enter your instrumentation key here>"
    }
}

Next add the Appliation Insights NuGet package:

dotnet add package Microsoft.ApplicationInsights.AspNetCore

Now create an interface called ITelemetry in the Services folder:

using System;

namespace ToDo.Services
{
    internal interface ITelemetry
    {
        void RecordExecutionTime(Type commandType, double executionTime);
    }
}

And an implementation called Telemetry:

using System;
using System.Collections.Generic;
using Microsoft.ApplicationInsights;

namespace ToDo.Services
{
    internal class Telemetry : ITelemetry
    {
        private readonly TelemetryClient _telemetryClient  = new TelemetryClient();

        public void RecordExecutionTime(Type commandType, double executionTime)
        {
            _telemetryClient.TrackEvent(commandType.Name, metrics: new Dictionary<string, double>
            {
                { "executionTimeMs",  executionTime}
            });
        }
    }
}

Now we need to decorate the default dispatcher with one that records our telemetry. To do this we need to implement the ICommandDispatcher as shown below, create a class called CustomDispatcher in the services folder:

using System.Diagnostics;
using System.Threading;
using System.Threading.Tasks;
using AzureFromTheTrenches.Commanding.Abstractions;
using AzureFromTheTrenches.Commanding.Abstractions.Model;

namespace ToDo.Services
{
    internal class CustomDispatcher : ICommandDispatcher
    {
        private readonly IFrameworkCommandDispatcher _underlyingDispatcher;
        private readonly ITelemetry _telemetry;

        public CustomDispatcher(
            IFrameworkCommandDispatcher underlyingDispatcher,
            ITelemetry telemetry
            )
        {
            _underlyingDispatcher = underlyingDispatcher;
            _telemetry = telemetry;
        }

        public async Task<CommandResult<TResult>> DispatchAsync<TResult>(ICommand<TResult> command, CancellationToken cancellationToken = new CancellationToken())
        {
            Stopwatch sw = Stopwatch.StartNew();
            CommandResult<TResult> result = await _underlyingDispatcher.DispatchAsync(command, cancellationToken);
            sw.Stop();
            _telemetry.RecordExecutionTime(command.GetType(), sw.ElapsedMilliseconds);
            return result;
        }

        public async Task<CommandResult> DispatchAsync(ICommand command, CancellationToken cancellationToken = new CancellationToken())
        {
            Stopwatch sw = Stopwatch.StartNew();
            CommandResult result = await _underlyingDispatcher.DispatchAsync(command, cancellationToken);
            sw.Stop();
            _telemetry.RecordExecutionTime(command.GetType(), sw.ElapsedMilliseconds);
            return result;
        }

        public ICommandExecuter AssociatedExecuter => null;
    }
}

The two DispatchAsync methods are responsible for dispatching commands to the appropriate handlers (which can be local or remote - see the documentation here) and the IFrameworkCommandDispatcher is the default implementation provided by the commanding framework (ICommandDispatcher is the interface used by consumers of the framework but we don't decorate it directly - IFrameworkCommandDispatcher is provided to avoid awkward to resolve circular situations).

We now need to register our dispatcher and telemetry service in our builder:

public void Build(IFunctionHostBuilder builder)
{
    builder
        .Setup((serviceCollection, commandRegistry) =>
        {
            // ...
            serviceCollection
                .AddSingleton(applicationSettings)
                .AddTransient<IToDoItemRepository, ToDoItemRepository>()
                .AddValidatorsFromAssemblyContaining<FunctionAppConfiguration>()
                // our additions
                .AddSingleton<ITelemetry, Telemetry>()
                .Replace(
                    new ServiceDescriptor(
                        typeof(ICommandDispatcher), 
                        typeof(CustomDispatcher),
                        ServiceLifetime.Transient)
                    )
                ;
            // ...
        })
        .AddFluentValidation() // as before
        .Authorization( /* as before */ )
        .DefaultHttpResponseHandler<HttpResponseHandler>() // as before
        .OpenApiEndpoint( /* as before */ )
        .Functions( /* as before */ );
}

If we run our project and execute a few commands in Postman then after a short delay we'll see our events logged in the Application Insights portal:

Adding a service bus queue function

In this final section lets assume that we also want to allow items to be marked as complete through the Service Bus queue. First we'll need to create a Service Bus namespace, you can follow the instructions here. In the portal also create a queue called newtodoitem (there's a button on the toolbar) and take note of the connection string for the RootManageSharedAccessKey in the Shared access policies section.

Next add the connection string to the local.settings.json file:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "cosmosConnectionString": "<enter your connection string here>",            
        "APPINSIGHTS_INSTRUMENTATIONKEY": "<enter your instrumentation key here>",
        "serviceBusConnectionString": "<enter your service bus connection string here>"
    }
}

Now add the Microsoft.Azure.WebJobs.Extensions.ServiceBus package to the project:

dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus

And now all we need to do is associate the AddToDoItemCommand we created earlier with an Azure Function triggered by our Service Bus queue:

    public void Build(IFunctionHostBuilder builder)
    {
        builder
            .Setup((serviceCollection, commandRegistry) => /* as before */)
            .AddFluentValidation() // as before
            .Authorization( /* as before */ )
            .DefaultHttpResponseHandler<HttpResponseHandler>() // as before
            .OpenApiEndpoint(/* as before */ )
            .Functions(functions => functions
                .HttpRoute("api/v1/todoItem", route => route
                    .HttpFunction<AddToDoItemCommand>(HttpMethod.Post)
                    .HttpFunction<GetAllToDoItemsQuery>(HttpMethod.Get)
                    .HttpFunction<MarkItemCompleteCommand>("/{itemId}/complete", HttpMethod.Put)
                )
                // Our addition
                .ServiceBus(serviceBus => serviceBus
                    .QueueFunction<AddToDoItemCommand>("newtodoitem")
                )
            );
    }

Now run the application and then, using the tool of your choice (for example Azure Service Bus Explorer), post the following item to the queue:

{
    "userId": "sbuser",
    "title": "Item from Service Bus"
}

This will result in the AddToDoItemCommandHandler being invoked, along with our validations, and the item being saved to Cosmos. Note that although we marked the UserId property with a SecurityProperty attribute those attributes only apply to HTTP triggers and so in this case we can set the UserId property.

This simple additon also demonstrates the value of separating out our concerns, and specifically the trigger from the business logic, as with just a few lines of code we've been able to invoke all our "add to do item" business logic via a different protocol.

Concluding

In addition to the features we've explored here there is support for other trigger types, output bindings and a varierty of cross cutting concerns details of which can be found in the projects documentation. And if you need to do something not supported by Function Monkey then standard Azure Functions can happily co-exist alongside Function Monkey functions.

Its also worth exploring the command framework in conjunction - the patterns explored here can be useful tools in organising large applications and evolving them from modular monoliths to microservice architectures, and the framework includes capabilities that allow execution to be both abstracted and remoted over various channels (message queues and HTTP for example). If you're interested in exploring this further then this series here may be useful along with this slidedeck.

Finally, this post has focused on C# and while it can be used in F# the builder pattern expressed in a C# style doesn't feel natural in that language. To address this a more F# friendly interface is under development and you can find details of that here.

If you have any questions please reach out to me in the comments or on Twitter.