Business Central Musings

Developing extensions for Microsoft Dynamics 365 Business Central can be a complex and time-consuming task, especially when it comes to keeping track of various components, objects, and their dependencies. That’s where Business Central ALDoc comes into play as an invaluable tool for developers.

ALDoc was introduced by Microsoft with the version of AL Language Extension that came with Business Central 2023 wave 1, spring-summer 2023. This is the official documentation.

You can find it on your Business Central DVD or, after installing AL Language, in your local folder :

C:\Users\[username]\.vscode\extensions\ms-dynamics-smb.al-12.1.883011\bin

Here it is as shown on my local folder:

One of the key features of ALDoc is its ability to create detailed documentation for your extension’s codebase. It automatically generates well-organized and easy-to-navigate documentation that includes information about the objects, fields, and functions used in your extension.

This not only helps developers understand your code but also assists in the onboarding of new team members. Additionally, with the new feature “Explore Page in Visual Studio Code” introduced in BC 2023 wave 2, having access to the extension architecture via ALDocs documentation, will prove to be a valuable tool for consultants. Ultimately, the documentation could be of big help to your partners, for cases when they need to leverage your extension via your own event publishers.

Over the summer, I read a few community blogs and videos on ALDocs and those were of great help to get me started. These blogs though stopped short of building a site that could be shared with your team or partners.

So, let’s go through:

• preparing the machine for generating AL extension documentation
• generate documentation
• find a methodology to share the documentation with any party you decide to share it with

In addition to reading, you might want to check my demonstration on YouTube:

Prepare machine to generate AL documentation

ALDocs is part of AL Language extension, but AL docs relies on having installed locally:

• .NET 6.00 or grater
• DocFx – a dot net open source package that makes it easier to build static sites

Check first what dot net version you have installed on your machine:

In your favorite terminal run:

dotnet --list -sdks

I have 6.0.400 so I am good to continue.

Install DocFx component:

Mine is already installed, so let’s go next.

Generate Documentation

I will create an output folder, but to be able to expose it as a open web site, I’m going to rely on a github repository that will act as a public site. This concept of exposing github repositories and act as sites is known as github pages.

1. Login in your Github account and create the Github repository for storing the ALDoc + DocFx generated documentation site

This site can be reached at https://[Github Username].github.io/RepositoryName.

In my case, that’s https://SilviuVirlan.github.io/QRCodes.

2. Clone this new repository on a local folder. This will act as the output for ALDoc Init and ALDoc Build commands.

3. Initialize site:

PS C:\Users\e096791\.vscode\extensions\ms-dynamics-smb.al-12.1.883011\bin> .\aldoc.exe init -o "C:\Docs\ALDocSites\QRCodes\SVQRCodes" -t "C:\Users\e096791\Documents\AL\ALProject57\SVirlan_SV QR Codes_23.0.0.0.app"
Writing root Table of Content
Writing configuration to aldoc.json

These are the switches I used above:

  -o, --output            Required. [required]: output path of intialization.

  -t, --targetpackages    Required. [required]: path of the source packages, splitted by ',' if you have multiple packages.

That will generate a structure similar to:

4. Build the site. The following command will parse your AL files and will build html files to serve as web pages for your objects:

PS C:\Users\e096791\.vscode\extensions\ms-dynamics-smb.al-12.1.883011\bin> .\aldoc.exe build -o "C:\Docs\ALDocSites\QRCodes\SVQRCodes" -s "C:\Users\e096791\Documents\AL\ALProject57\SVirlan_SV QR Codes_23.0.0.0.app"
warning: Referenced module not loaded. Name:'Application', Version:23.0.0.0, AppId:00000000-0000-0000-0000-000000000000
Writing Content
Writing Obsoletion Lists
Writing Table of Content


Build succeeded with warning.

    1 warning(s)
    0 error(s)

We used two switches:
 -s, --source                 Required. [required]: path to package file (*.app) to build documentation for.

  -o, --output                 Required. [required]: the destination folder where the generated documentation is 

Now the local repository for site looks like this:

5. Build the actual site with DocFx:

PS C:\Users\e096791\.vscode\extensions\ms-dynamics-smb.al-12.1.883011\bin> docfx build "C:/Docs/ALDocSites/QRCodes/SVQRCodes/docfx.json"

Searching custom plugins in directory C:\Users\e096791\.dotnet\tools\.store\docfx\2.70.0\docfx\2.70.0\tools\net6.0\any\...
6 plug-in(s) loaded.
No files are found with glob pattern override_files/**.md, excluding <none>, under directory "C:\Docs\ALDocSites\QR Codes\QRCodes"
2 schema driven document processor plug-in(s) loaded.
Building 2 file(s) in TocDocumentProcessor(BuildTocDocument)...
Building 7 file(s) in BusinessCentralApplicationObject(BuildSchemaBasedDocument=>ApplyOverwriteFragments=>ApplyOverwriteDocument=>ApplyTags)...
Building 1 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>CountWord=>ValidateConceptualDocumentMetadata)...
Applying templates to 9 model(s)...
XRef map exported.
Manifest file saved to manifest.json.
Completed building documents in 2174.9695 milliseconds.

The outcome is that now we have a _site folder:

6. Let’s start the web server locally:

PS C:\Users\e096791\.vscode\extensions\ms-dynamics-smb.al-12.1.883011\bin> docfx serve "C:/Docs/ALDocSites/QRCodes/SVQRCodes/_site"

Serving "C:\Docs\ALDocSites\QR Codes\QRCodes\_site" on http://localhost:8080. Press Ctrl+C to shut down.

We navigate to http://localhost:8080 and we can see the documentation site:

This site runs locally, so nobody outside of my machine can access it.

How do we expose it externally?

Recall that at Step 1 and 2 I created a github repository and cloned it locally? Let’s turn this repository into a Github page.

7. Let’s commit/publish the local folder to github repo:

8. Turn github repository into a github page (github site).

In github, locate Settings action, then choose Pages blade and setup your branch and Save:

Once that’s done you can access the github repository like this:

https://SilviuVirlan.github.io/QRCodes:

But we don’t actually see the documentation for our extension.

The page needs the files in the _site folder to be located on the main folder.

9. Copy locally the content of the _site folder in the main folder. Push changes to github:

After copy, and push, navigate to the Settings page for the repository, Pages blade:

And, finally we can see the github hosted documentation site https://silviuvirlan.github.io/SVQRCodes

Final words

In conclusion, if you’re a developer working with Microsoft Dynamics 365 Business Central and you want to ensure that your extensions are well-documented and easy to maintain, Business Central ALDoc and DocFx are tools that can save you time and effort. Its ability to automatically generate comprehensive documentation and support custom comments within your code can greatly improve collaboration, understanding, and long-term sustainability. So, if you haven’t already, consider integrating ALDoc into your development workflow to make the extension development process smoother and more efficient.