In this Areopa webinar, Eric “waldo” Wauters (iFacto Business Solutions) presents the ALGuidelines.Dev initiative, moderated by Tobias Fenster. Waldo explains where the project comes from, how the community and Microsoft collaborate on it, and how AL developers can both use and contribute to it. He closes with a walkthrough of a few concrete patterns and guidelines that his own company relies on daily.
The Revival of a Diamond
Waldo starts with the history behind the initiative. Back in 2011-2012, Microsoft’s Bogdana Botez set out to document what was, at the time, completely undocumented: NAV development patterns and internal guidelines. The result was the NAV Design Patterns Wiki, hosted on community.dynamics.com, where the community could propose patterns and guidelines for Microsoft to review and publish.
It documented well-known patterns such as the Number Series pattern, as well as newer ones like the Hooks pattern. Over time, the wiki became difficult to browse and eventually stalled as AL replaced C/AL and as new extensibility concepts emerged that the wiki never covered.
📖 Reference: AL Development Guideline #1: the “NAV Design Patterns Wiki” — waldo’s blog post that first pointed the community back to the original wiki.
How ALGuidelines.Dev Was Born
In 2020, Waldo gave a DynamicsCon session called “AL Development Design Patterns for the Future,” arguing that the community needed to pick up where the NAV Design Patterns Wiki left off. He didn’t know how to organize it at scale, so he started publishing individual guidelines on his own blog instead, starting with a post that simply pointed back to the wiki.
That post caught the attention of Jeremy Vyska, who proposed scraping the entire wiki and turning it into a proper repository. Waldo then reached out to Henrik Helgesen and AJ Kauffmann, who suggested using GitHub Pages so the community could contribute the way developers already know how to: forks and pull requests. Because the source content belonged to Microsoft, the group needed permission to reuse it, which brought Jesper Schulz-Wedde and Freddy Kristiansen into the conversation — and turned the project into an active collaboration with Microsoft rather than just a community scrape.
Jeremy built the tooling that converted the wiki’s HTML pages into Markdown files, which now form the content of the site. The project’s goals became: preserve what already existed, describe new AL-specific patterns, and make it possible for anyone to contribute, discuss, and improve guidelines through pull requests.
📖 Reference: The “ALGuidelines.Dev” initiative – revival of a diamond — waldo’s full write-up of how the initiative came together.
Patterns vs. Guidelines
Waldo draws a clear line between the two terms the site uses throughout:
- Pattern — a model or example, something to copy, that only applies in certain scenarios to solve a specific problem. Applied to the wrong problem, a pattern becomes an anti-pattern.
- Guideline — a rule or principle that sets a standard and should always be applied.
Exploring alguidelines.dev
The site itself is a Hugo static site built from Markdown files and published through GitHub Pages. The docs section is organized by category — Design Patterns, Best Practices, and the NAV Patterns Archive for the content carried over from the original wiki — and every page carries tags so related guidelines and patterns can be found together (for example, everything tagged “API”).
Each page links to a discussion thread and an “edit this page” action, and any disagreement about a pattern plays out openly — Waldo points to an active discussion about whether begin..end compounds should be used for single-line statements as a good example of that.
📖 Docs: alguidelines.dev — the live site: guidelines and patterns for Business Central AL development, community-run and Microsoft-endorsed.
Why Microsoft’s Involvement Matters
The repository is hosted under the Microsoft organization on GitHub, which shapes the project in a few ways. Microsoft engineers sit on the approval team alongside community members — currently including Waldo, AJ Kauffmann, Jeremy Vyska, and others — so every merged guideline has had review from people who also work on the product. Contributors sign a Contributor License Agreement, which means Microsoft can adopt whatever patterns and guidelines the community lands on directly into the base app and system app.
How to Contribute
Because the site is generated from Markdown, contributing follows the same flow as any other open source project:
- Fork the GitHub repository.
- Make your changes.
- Open a pull request back to Microsoft’s repository.
The Contributing section of the site provides copy-paste templates for both patterns and best practices, so contributors only need to fill in the specifics: description, problem, context, usage, when not to use it, and bad/good code examples. Small edits can even be made directly in the browser using the GitHub.dev editor. For anything involving more complex Markdown, Waldo installs Hugo locally so he can preview exactly how a new page will render before opening a pull request — the site he demonstrates rebuilds automatically as he edits and saves a file.
Every pull request goes through review by a minimum of three of the six designated reviewers before it’s merged, which Waldo notes tends to be a fairly thorough process — he walks through a closed pull request for the Number Series pattern where several reviewers left detailed comments before it was approved.
📖 Reference: Contributing to “ALGuidelines.Dev” — waldo’s step-by-step guide to forking, running Hugo locally, and submitting a pull request. Repository: github.com/microsoft/alguidelines.
Applying This to Your Organization
Waldo argues that every development team needs a shared set of guidelines, if only so everyone writes the same kind of code the same way — down to details like where begin..end goes. ALGuidelines.Dev gives a team a reference point to start from, even where the site’s own conventions are debatable.
Two practices he recommends for embedding this in a company:
- Use code review as the main mechanism for enforcing guidelines and getting a read on where individual developers need more guidance.
- Turn a small set of guidelines and patterns into mandatory knowledge for the team, so referring to a pattern by name (like “the Discovery pattern”) is enough of a shared vocabulary to communicate a design.
A Look at Current AL Guidelines and Patterns
With time left in the session, Waldo walks through a handful of guidelines and patterns that are live on the site today.
If/else formatting
A straightforward but frequently debated example: keeping if and else statements on separate lines. Waldo shows the guideline’s own bad/good code comparison.
API Page / Query
Waldo calls out the mandatory fields guideline for API pages as one of the most important on the site: SystemId should always be exposed as the field named id, and SystemModifiedAt as lastModifiedDateTime. Naming these fields differently breaks how the resulting API endpoint behaves for consumers.
📖 Docs: API Page / Query — the full best-practice page, including page properties, versioning, and the mandatory-fields guidance Waldo walks through.
Façade pattern
Described on the site by Jesper Schulz-Wedde, the Façade pattern is heavily used throughout the Business Central system app. A single public codeunit — the facade — exposes the methods an extension is meant to call, while everything the facade delegates to underneath is internal and off-limits to dependent extensions. Waldo recommends reading through the pattern description as a way to understand how the system app itself is structured.
📖 Docs: Façade pattern — improves API readability, keeps internal implementation swappable, and enforces encapsulation between an extension’s public surface and its internals.
Generic Method pattern
The pattern Waldo says his company relies on the most: every isolated piece of business logic gets its own encapsulated method with a consistent “before” and “after” moment built in. Because every method exposes an after-hook by construction, other extensions have a predictable, single place to subscribe to instead of guessing at execution order across multiple event subscribers.
📖 Docs: Generic Method pattern — covers extensibility, decoupling, testability, and encapsulation benefits, along with a full code example.
Q&A Highlights
During the Q&A, a viewer asked whether a code analyzer (a “code cop”) could eventually be built to enforce these guidelines automatically. Waldo said he believed it was possible and pointed to work already underway on that front. That effort became BusinessCentral.LinterCop, a community-driven AL code analyzer that checks code against exactly this kind of guideline.
Asked whether any of these patterns might end up as AL code snippets, Waldo confirmed that’s part of the plan — the Generic Method pattern page already includes a snippet, and he was considering splitting snippets out of his existing VS Code extension into a dedicated one built around ALGuidelines.Dev content.
Getting Involved
Waldo closes by pointing to the site’s Discussions section, used both to work out a pattern before it’s written up and to track a running to-do list of guidelines the team still wants to describe. He encourages anyone with feedback — positive or negative — on an existing or proposed pattern to join the conversation there.
📖 Docs: GitHub Discussions — where the ALGuidelines.Dev community proposes, debates, and refines patterns and guidelines.
This post was drafted with AI assistance based on the webinar transcript and video content.