<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Albert Assaad on Medium]]></title>
        <description><![CDATA[Stories by Albert Assaad on Medium]]></description>
        <link>https://medium.com/@albertassaad?source=rss-5b48dd238294------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/2*vtXDABYcCHc-lKKfM7CD8A.png</url>
            <title>Stories by Albert Assaad on Medium</title>
            <link>https://medium.com/@albertassaad?source=rss-5b48dd238294------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 00:37:44 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@albertassaad/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Get an Instant Email Alert When Someone Plugs a USB Into Your PC (Windows 11)]]></title>
            <link>https://albertassaad.medium.com/get-an-instant-email-alert-when-someone-plugs-a-usb-into-your-pc-windows-11-fcc594e51a5c?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/fcc594e51a5c</guid>
            <category><![CDATA[information-security]]></category>
            <category><![CDATA[automation]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[powershell]]></category>
            <category><![CDATA[windows]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Wed, 21 Oct 2026 12:51:58 GMT</pubDate>
            <atom:updated>2026-10-22T06:03:33.195Z</atom:updated>
            <content:encoded><![CDATA[<h3>Part 2 of my USB detection guide: turn Event Viewer’s USB events into a silent email, a log file and an optional popup, using only tools already built into Windows.</h3><p>In my previous article, <a href="https://albertassaad.medium.com/know-if-a-usb-is-inserted-to-your-pc-windows-10-6d177758cf73">How to Detect USB Insertions on Windows (Even When You’re Away)</a>, we turned on a hidden Windows log that records every time a USB device is connected or removed. It works well, but it has one obvious catch: logs tell you what happened, not while it’s happening. You only find out later, when you remember to go and look.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/880/1*de0BPUIwcJBmmXqwehuT2A.png" /></figure><p>In this article we’ll close that gap. By the end, every time a USB storage device is plugged into your PC, Windows will do three things on its own:</p><ol><li>Add a line with the date and time to a log file.</li><li>Send you an email in the background. Nothing appears on screen, so whoever plugged in the USB doesn’t know it happened.</li><li>Optionally, show a popup saying the insertion has been logged.</li></ol><p>Why both an email and a popup? A popup is only seen by whoever is sitting at the PC. If that’s you, great. If it’s someone else while you’re out, they simply click OK and carry on. The email is what reaches you when you’re away. The popup becomes a warning to the other person, and you can turn it off if you’d rather stay invisible.</p><p>No third-party software. We’ll use Event Viewer, Task Scheduler, a Gmail account, and one PowerShell script. The steps and menu names below are from Windows 11, and the same steps work on Windows 10.</p><h3>How it works</h3><p>When a USB storage device is connected, Windows writes Event ID 2003 to the DriverFrameworks-UserMode log. Task Scheduler can watch for a specific event and run something the moment that event appears. Event Viewer has a shortcut that builds this kind of task for you, so we’ll use it, then point the task at our PowerShell script.</p><pre>USB plugged in -&gt; Event ID 2003 logged -&gt; Task Scheduler fires -&gt; UsbAlert.ps1 runs -&gt; log line + email + popup</pre><h3>Step 1: Make sure the USB log is enabled</h3><p>If you followed the first article, this is already done and you can skip ahead. If not, it takes ten seconds. This log is off by default, and without it nothing in this article will fire.</p><ol><li>Press Win + R, type eventvwr.msc, and press Enter.</li><li>In the left pane, expand <strong>Applications and Services Logs &gt; Microsoft &gt; Windows &gt; DriverFrameworks-UserMode</strong>.</li><li>Right-click <strong>Operational</strong> and choose <strong>Enable Log</strong>. (If you see <strong>Disable Log</strong> instead, it’s already on.)</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FZwHNRE85ZCFkWz9YCxMyg.png" /></figure><p>Now plug in any USB flash drive and click <strong>Refresh</strong> in the right pane. You should see at least one event with Event ID 2003 (as covered in part one, 2003 means connected and 2102 means removed). We need one of those in Step 4.</p><h3>Step 2: Prepare a Gmail account to send the alerts</h3><p>The script sends the email through Gmail. I strongly recommend creating a new Gmail account just for this, rather than using your main one. The script needs that account’s password stored on the PC, so if it ever leaks, the worst case is someone gets into an empty alert account. The alert itself can go to any address you like, including your main inbox.</p><p>Gmail won’t accept your normal password from a script. It needs an app password, which only exists once 2-Step Verification is on.</p><ol><li>Sign in to the new account and open <strong>Manage your Google Account &gt; Security</strong>.</li><li>Turn on <strong>2-Step Verification</strong> and follow Google’s steps.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Hk9286eTeLvdzsMuCfyWTQ.png" /></figure><ol><li>Go to myaccount.google.com/apppasswords, type a name such as USB Alert, and click <strong>Create</strong>.</li><li>Google shows a 16-character password once. Copy it somewhere for the next step.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Yr01FdHkXQxh9iFQe0s91Q.png" /></figure><h3>Step 3: Create the script and store the password</h3><h3>Create the script</h3><ol><li>Create a folder called C:\UsbAlerts.</li><li>Open Notepad and paste the script below.</li><li>Change $From to your new alert Gmail address and $To to the address where you want to receive the alert.</li><li>Choose <strong>File &gt; Save as</strong>, set “Save as type” to <strong>All files</strong>, and save it as C:\UsbAlerts\UsbAlert.ps1.</li></ol><p>That last detail matters. If you leave the type as “Text documents”, Notepad quietly saves it as UsbAlert.ps1.txt and the task will fail.</p><pre># UsbAlert.ps1<br># Runs from Task Scheduler every time Event ID 2003 is logged<br># (a USB device was connected). In order, it:<br>#   1. writes a line to a log file,<br>#   2. emails you in the background (nothing appears on screen),<br>#   3. shows a popup on the desktop (optional).<br># The popup comes last on purpose: closing it can&#39;t stop the log or the email.<br># --- Settings -------------------------------------------------------<br>$LogFolder  = &#39;C:\UsbAlerts&#39;<br>$LogFile    = Join-Path $LogFolder &#39;usb-log.txt&#39;<br>$SendEmail  = $true                          # $false to turn email off<br>$SmtpServer = &#39;smtp.gmail.com&#39;<br>$SmtpPort   = 587<br>$From       = &#39;your.alert.account@gmail.com&#39; # the Gmail account that sends<br>$To         = &#39;you@example.com&#39;              # where you want the alert<br>$CredFile   = Join-Path $LogFolder &#39;smtp-cred.xml&#39;<br>$ShowPopup  = $true                          # $false for a fully silent alert<br># --- 1. Write to the log file ---------------------------------------<br>if (-not (Test-Path $LogFolder)) {<br>    New-Item -Path $LogFolder -ItemType Directory -Force | Out-Null<br>}<br>$timestamp = Get-Date -Format &#39;yyyy-MM-dd HH:mm:ss&#39;<br>$line = &quot;$timestamp  USB device connected on $env:COMPUTERNAME (user: $env:USERNAME)&quot;<br>Add-Content -Path $LogFile -Value $line<br># --- 2. Send the email in the background ----------------------------<br>if ($SendEmail) {<br>    try {<br>        # Gmail requires TLS 1.2<br>        [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12<br>        # The app password is stored encrypted (see the one-time setup)<br>        $cred = Import-Clixml -Path $CredFile<br>        $mail = New-Object System.Net.Mail.MailMessage($From, $To)<br>        $mail.Subject = &quot;USB alert on $env:COMPUTERNAME&quot;<br>        $mail.Body    = $line<br>        $smtp = New-Object System.Net.Mail.SmtpClient($SmtpServer, $SmtpPort)<br>        $smtp.EnableSsl   = $true<br>        $smtp.Credentials = $cred.GetNetworkCredential()<br>        $smtp.Send($mail)<br>        $mail.Dispose()<br>        $smtp.Dispose()<br>    }<br>    catch {<br>        # No internet, wrong password, etc. The log line above is already saved.<br>        Add-Content -Path $LogFile -Value &quot;$timestamp  Email failed: $($_.Exception.Message)&quot;<br>    }<br>}<br># --- 3. Show the desktop alert (optional) ---------------------------<br>if ($ShowPopup) {<br>    Add-Type -AssemblyName System.Windows.Forms<br>    # An invisible &quot;TopMost&quot; form keeps the popup on top of other windows<br>    $owner = New-Object System.Windows.Forms.Form<br>    $owner.TopMost = $true<br>    $message = &quot;This USB insertion has been logged.`n`nTime: $timestamp&quot;<br>    [System.Windows.Forms.MessageBox]::Show(<br>        $owner,<br>        $message,<br>        &#39;USB Alert&#39;,<br>        [System.Windows.Forms.MessageBoxButtons]::OK,<br>        [System.Windows.Forms.MessageBoxIcon]::Warning<br>    ) | Out-Null<br>    $owner.Dispose()<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LUg0p8Cm62a1YmGvN415Kg.png" /></figure><p>A few notes on how the script is built:</p><ol><li>The order matters. The log line and the email happen before the popup, because the popup waits until someone clicks OK. Whoever closes it is too late to stop anything.</li><li>Everything uses .NET classes that ship with Windows (System.Net.Mail for the email, System.Windows.Forms for the popup), so there&#39;s nothing to install.</li><li>If the email fails (no internet, wrong password), the script doesn’t crash. It writes the error to the log, so you can see what went wrong.</li><li>Set $ShowPopup = $false if you want the alert to be completely silent on the PC.</li></ol><h3>Store the app password, encrypted</h3><p>We don’t want the password sitting in the script in plain text. Instead, PowerShell can save it encrypted to your Windows account.</p><ol><li>Open <strong>Windows PowerShell</strong> (not as administrator; use your normal account, the same one the task will run as).</li><li>Run this command:</li></ol><pre>Get-Credential | Export-Clixml -Path &#39;C:\UsbAlerts\smtp-cred.xml&#39;</pre><ol><li>In the window that opens, enter the alert Gmail address as the user name and the 16-character app password as the password.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vYIwf00rlODgjIcYIugnNw.png" /></figure><p>This creates smtp-cred.xml. The password inside is encrypted with Windows&#39; Data Protection API, so it only decrypts for your user account on this PC. Copying the file to another computer gives you nothing.</p><h3>Step 4: Attach a task to the USB event</h3><p>Now the fun part. Back in Event Viewer:</p><ol><li>Select <strong>Operational</strong> under DriverFrameworks-UserMode.</li><li>In the middle list, find an event with Event ID <strong>2003</strong>.</li><li>Right-click it and choose <strong>Attach Task To This Event…</strong></li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Bxzv9NKForPzSs_JFzkBzQ.png" /></figure><p>This opens the <strong>Create Basic Task Wizard</strong>. Go through it like this:</p><ol><li><strong>Create a Basic Task</strong>: Windows fills in a long name automatically. Replace it with something readable, like USB Insert Alert, and add a description if you want. Click <strong>Next</strong>.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/696/1*mvd655ItASLSruvXmZn3_w.png" /></figure><ol><li><strong>When a Specific Event Is Logged</strong>: this page is already filled in for you (Log: Microsoft-Windows-DriverFrameworks-UserMode/Operational, Source: DriverFrameworks-UserMode, Event ID: 2003). There’s nothing to change here, which is exactly why we used this shortcut. Click <strong>Next</strong>.</li><li><strong>Action</strong>: choose <strong>Start a program</strong> and click <strong>Next</strong>. You’ll notice the other two options are labeled “Send an e-mail (deprecated)” and “Display a message (deprecated)”. Microsoft deprecated both back in Windows 8 and recommends running PowerShell instead, which is what we’re doing.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/696/1*-WJD56RIX9Rm4HsZkCSnfQ.png" /></figure><ol><li><strong>Start a Program</strong>: fill in the fields exactly as below, then click <strong>Next</strong>.</li></ol><ul><li>Program/script:</li></ul><pre>powershell.exe</pre><ul><li>Add arguments (optional):</li></ul><pre>-ExecutionPolicy Bypass -WindowStyle Hidden -File &quot;C:\UsbAlerts\UsbAlert.ps1&quot;</pre><ul><li>Start in (optional): leave empty.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/696/1*5Yag5oCvhKNUKjBA7CwwZQ.png" /></figure><ol><li><strong>Finish</strong> (the last page of the wizard): tick the box <strong>Open the Properties dialog for this task when I click Finish</strong>, then click <strong>Finish</strong>. We need that Properties window for the next step.</li></ol><p>About those arguments: -ExecutionPolicy Bypass lets this one script run even if your PC blocks scripts by default, without changing any system setting. -WindowStyle Hidden hides the PowerShell console (you may still see it flash for a split second, which is normal). -File points to the script.</p><h3>Step 5: Adjust the important task settings</h3><p>The Properties window opens with several tabs. Three of them need your attention.</p><h3>General tab</h3><p>Make sure <strong>Run only when user is logged on</strong> is selected, under your own user account. This is the default for tasks created this way, but check it anyway.</p><p>It matters for two reasons. The popup can only appear on a desktop where you’re signed in. And the encrypted password from Step 3 only decrypts for your account, so the task has to run as you for the email to work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/632/1*-kaRkx2OP2tt7mErUKZcNg.png" /></figure><h3>Conditions tab</h3><p>Under <strong>Power</strong>, uncheck <strong>Start the task only if the computer is on AC power</strong>. On a laptop running on battery, Windows would otherwise skip the task silently.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/632/1*znGxXr7qGaQaFeQVpqvT1g.png" /></figure><h3>Settings tab</h3><p>Look at the last option, <strong>If the task is already running, then the following rule applies</strong>, and make sure it’s set to <strong>Do not start a new instance</strong>.</p><p>Here’s why. Plugging in one flash drive can log Event ID 2003 more than once, because Windows may load drivers for more than one part of the same device. This setting stops you from getting several identical emails and popups for a single insertion.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/632/1*pradH8TrN1cvYGjm2U9VkA.png" /></figure><p>Click <strong>OK</strong> to save. If Windows asks for your password, enter it.</p><p>You can always find the task later in Task Scheduler under <strong>Task Scheduler Library &gt; Event Viewer Tasks</strong>.</p><h3>Step 6: Test it</h3><ol><li>Plug in a USB flash drive.</li><li>Within a few seconds, the popup appears (if you left $ShowPopup on).</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*77gf3qCLiseZ_GEaZjTljg.png" /></figure><ol><li>Check the inbox you set in $To. You should have an email with the subject &quot;USB alert on&quot; followed by your computer name. Check the spam folder the first time, and mark it as &quot;Not spam&quot; if it landed there.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lGbVOXxPMNBC3MPfpGAZvg.png" /></figure><p>2. Open C:\UsbAlerts\usb-log.txt. You should see a line like this:</p><pre>2026-10-21 14:32:07  USB device connected on DESKTOP-ALBERT (user: User)</pre><p>If the email didn’t arrive, the log file will usually tell you why, on a line starting with “Email failed”.</p><h3>Troubleshooting</h3><h3>The email doesn’t arrive</h3><p>Open usb-log.txt and look for a line starting with &quot;Email failed&quot;. The message usually points to the cause:</p><ol><li>“Authentication” or “5.7.0” errors mean Gmail rejected the login. Check that 2-Step Verification is on and that you saved the app password, not your normal Gmail password, in Step 3.</li><li>“Key not valid for use in specified state” means smtp-cred.xml was created under a different Windows account than the one running the task. Run the Get-Credential command again from your normal account.</li><li>A “could not connect” error means the PC had no internet, or a firewall is blocking port 587.</li></ol><p>And if there’s no error at all, check the spam folder.</p><h3>No popup appears, but the log file gets updated</h3><p>The task is running, just not on your desktop. On the General tab, it must be set to <strong>Run only when user is logged on</strong> under your own account. Also, if an earlier popup is still open (or a PowerShell process is stuck), “Do not start a new instance” blocks new runs; end any leftover Windows PowerShell processes in Task Manager and try again.</p><h3>The script is blocked by the execution policy</h3><p>With -ExecutionPolicy Bypass, this shouldn&#39;t happen on a home PC. On a work or school computer, a Group Policy setting can override the switch. Run Get-ExecutionPolicy -List: a value next to MachinePolicy or UserPolicy means it&#39;s managed by your IT team.</p><h3>The task never runs when you plug in a USB</h3><p>Open Task Scheduler, select the task, and check the <strong>Last Run Result</strong> column and the <strong>History</strong> tab. If the task never fired, the DriverFrameworks-UserMode Operational log is probably not enabled, so Event ID 2003 is never written. Go back to Step 1. If the task did fire but did nothing, check that the script wasn’t saved as UsbAlert.ps1.txt (turn on <strong>View &gt; Show &gt; File name extensions</strong> in File Explorer), then run it by hand to see any errors:</p><pre>powershell.exe -ExecutionPolicy Bypass -File &quot;C:\UsbAlerts\UsbAlert.ps1&quot;</pre><h3>Wrapping up</h3><p>That’s it. Part one gave us the record of what happened; this part makes Windows email you the moment it happens, even when you’re nowhere near your desk. All with tools that were already sitting on your PC: one log, one scheduled task, and one PowerShell script.</p><p>If you get stuck on any step, or you build one of the “going further” ideas and want to share it, feel free to ask in the comments section.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fcc594e51a5c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AL Development in Business Central Part 6: API Pages, OData, and Bound Actions]]></title>
            <link>https://albertassaad.medium.com/al-development-in-business-central-part-6-api-pages-odata-and-bound-actions-8da530048da2?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/8da530048da2</guid>
            <category><![CDATA[erp-software]]></category>
            <category><![CDATA[odata]]></category>
            <category><![CDATA[rest-api]]></category>
            <category><![CDATA[dynamics-365]]></category>
            <category><![CDATA[business-central]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Wed, 30 Sep 2026 15:54:06 GMT</pubDate>
            <atom:updated>2026-09-30T15:54:06.706Z</atom:updated>
            <content:encoded><![CDATA[<p>In <a href="https://medium.com/@albertassaad/al-development-in-business-central-part-5-table-extensions-page-extensions-and-events-4a1c535c60c5">Part 5</a> we stopped editing our own objects and started extending Microsoft’s: a tableextension on Customer, a pageextension on the Customer Card, and an event subscriber that reacted to a field being validated.</p><p>Everything so far lives inside Business Central. That’s fine until somebody asks: “Can our other system read this?”</p><p>This part answers that. We’ll expose the Project Task table from <a href="https://medium.com/@albertassaad/building-your-first-real-al-objects-tables-pages-and-a-codeunit-in-business-central-4e1bfe3823f9">Part 4</a> as a REST endpoint, so an external system can list tasks, create them, filter by status, and call our Complete Task logic over HTTP.</p><p>The page itself is about forty lines. The hard part is that four things have to line up before a single call succeeds: the extension has to compile against another extension, the container has to serve the API stack, the URL has to be exactly right, and the credentials have to be the kind the API accepts. Get one wrong and the error doesn’t explain itself, so I’ve written this part as much around the errors as the code. Every one below is a message I actually got.</p><h3>What an API page actually is</h3><p>An API page is a page object with PageType = API. It has no UI. Its only purpose is to be a URL. Unlike publishing a normal page as an OData web service, everything about the endpoint is declared in the object. There&#39;s no Web Services page and no admin step: publish the extension and the endpoint exists.</p><p>Five properties define the URL:</p><ol><li>APIPublisher: the first segment, usually you or your company</li><li>APIGroup: the second segment, a grouping of related endpoints</li><li>APIVersion: the third segment, such as v1.0 or beta</li><li>EntityName: the singular name of one record</li><li>EntitySetName: the plural name, which is what appears in the URL</li></ol><p>Leave out APIPublisher, APIGroup, EntityName or EntitySetName and the compiler stops you with AL0485. Use camelCase for all of them. CodeCop rule AA0101 warns on casing violations, and ignoring it makes your endpoint look out of place next to the built-in APIs.</p><h3>The dependency problem</h3><p>The API gets its own project. Make a folder called ProjectTaskApi, run AL: Go! inside it, point it at your container, and delete HelloWorld. In app.json, set the ID range to 50200 through 50249.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jNegB8Ckf0gsuDu_ZFe59g.png" /><figcaption>A clean project with its numbers to work with.</figcaption></figure><p>Create Pag50200.ProjectTasksAPI.al with a stub that points at our table:</p><pre>page 50200 &quot;Project Tasks API&quot;<br>{<br>    PageType = API;<br>    SourceTable = &quot;Project Task&quot;;<br>}</pre><p>Save it, and the compiler underlines &quot;Project Task&quot; in red before you&#39;ve published anything.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yjXYfBHjtC1MuT_A6hYigQ.png" /><figcaption>The error that starts this whole section.</figcaption></figure><p>It’s right. Project Task isn’t in the base application, it lives in the Part 4 extension, and a separate project can’t see another extension’s objects until you declare a dependency. Open the Part 4 project’s app.json, copy its id, name, publisher and version, and put them in the new project&#39;s app.json:</p><pre>&quot;dependencies&quot;: [<br>  {<br>    &quot;id&quot;: &quot;b12712c1-6567-4d47-bb5e-7421bb58616a&quot;,<br>    &quot;name&quot;: &quot;Example&quot;,<br>    &quot;publisher&quot;: &quot;Albert Assaad&quot;,<br>    &quot;version&quot;: &quot;1.0.0.0&quot;<br>  }<br>],<br>&quot;idRanges&quot;: [<br>  {<br>    &quot;from&quot;: 50200,<br>    &quot;to&quot;: 50249<br>  }<br>]</pre><p>Those are my values. Read yours out of your own file.</p><p>Since 2021 wave 2, an app’s identity is its id alone. But symbol download still matches on name, publisher and minimum version, so get the name or publisher wrong and the download can&#39;t find the app, with an error that reads as if it was never published. The version is a minimum: you get the newest installed version that satisfies it.</p><p>Two more steps before this compiles, and the order matters:</p><ol><li>Make sure the Part 4 extension is published to the container. Symbols come from the server, and the server can only serve extensions it has. If it’s not published, open the Part 4 project and press F5.</li><li>Run AL: Download Symbols in the new project. The output window should list a .app named after your Part 4 extension alongside System and Base Application. If it&#39;s missing, stop and fix the dependency before going on.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_ceb_a5kIXTQGESwn4vANQ.png" /><figcaption>This line is the one that matters. If your Part 4 app isn’t in the list, the dependency is wrong.</figcaption></figure><h3>Making sure the container is serving APIs</h3><p>On-premises, the API stack can be off, and then every call returns 405 Method Not Allowed. That sounds like you used the wrong verb. Here it means the endpoint isn’t being served at all.</p><p>ODataServicesEnabled and ApiServicesEnabled control this. BcContainerHelper containers normally have both on. Check from PowerShell on the host:</p><pre>Get-BcContainerServerConfiguration -containerName bcserver |<br>    Select-Object ODataServicesEnabled, ApiServicesEnabled, ODataServicesPort</pre><p>If either says False, turn it on inside the container:</p><pre>Invoke-ScriptInBcContainer -containerName bcserver -scriptblock {<br>    Set-NAVServerConfiguration -ServerInstance BC -KeyName ApiServicesEnabled -KeyValue true<br>    Set-NAVServerConfiguration -ServerInstance BC -KeyName ODataServicesEnabled -KeyValue true<br>    Restart-NAVServerInstance -ServerInstance BC<br>}</pre><p>bcserver is my container name. Substitute yours everywhere (docker ps will remind you). The server instance inside the container is always BC, and the OData port is 7048.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L0Xnj5T37qw9ZvbtEWQB5g.png" /><figcaption>What a healthy container looks like before you write a single line of the API page.</figcaption></figure><h3>The API page</h3><p>Replace the stub with the real page:</p><pre>page 50200 &quot;Project Tasks API&quot;<br>{<br>    PageType = API;<br>    Caption = &#39;Project Tasks API&#39;;<br>    APIPublisher = &#39;albertassaad&#39;;<br>    APIGroup = &#39;projectMgmt&#39;;<br>    APIVersion = &#39;v1.0&#39;;<br>    EntityName = &#39;projectTask&#39;;<br>    EntitySetName = &#39;projectTasks&#39;;<br>    EntityCaption = &#39;Project Task&#39;;<br>    EntitySetCaption = &#39;Project Tasks&#39;;<br>    SourceTable = &quot;Project Task&quot;;<br>    ODataKeyFields = SystemId;<br>    DelayedInsert = true;<br>    Extensible = false;<br><br>    layout<br>    {<br>        area(Content)<br>        {<br>            repeater(Group)<br>            {<br>                field(id; Rec.SystemId)<br>                {<br>                    Caption = &#39;Id&#39;;<br>                    Editable = false;<br>                }<br>                field(number; Rec.&quot;No.&quot;)<br>                {<br>                    Caption = &#39;Number&#39;;<br>                }<br>                field(description; Rec.Description)<br>                {<br>                    Caption = &#39;Description&#39;;<br>                }<br>                field(status; Rec.Status)<br>                {<br>                    Caption = &#39;Status&#39;;<br>                }<br>                field(dueDate; Rec.&quot;Due Date&quot;)<br>                {<br>                    Caption = &#39;Due Date&#39;;<br>                }<br>                field(completedOn; Rec.&quot;Completed On&quot;)<br>                {<br>                    Caption = &#39;Completed On&#39;;<br>                    Editable = false;<br>                }<br>                field(lastModifiedDateTime; Rec.SystemModifiedAt)<br>                {<br>                    Caption = &#39;Last Modified Date&#39;;<br>                    Editable = false;<br>                }<br>            }<br>        }<br>    }<br><br>    trigger OnOpenPage()<br>    begin<br>        Rec.ReadIsolation := IsolationLevel::ReadCommitted;<br>    end;<br>}</pre><p>ODataKeyFields = SystemId is the line people skip and regret. SystemId is a GUID the platform assigns once and never changes. Our primary key, &quot;No.&quot;, is a Code[20] a user typed and could retype, so keying the API on it would break every external reference on a rename. Power Automate and Power Apps also expect a single GUID key.</p><p>Two rules come with it: the key field must be a control on the page (AL0615), and API pages need DelayedInsert = true (AL0505), so the record is fully populated from the request body before it&#39;s inserted.</p><p>The control names (number, dueDate, completedOn) are what go over the wire as JSON properties. I used number rather than no because it reads better and matches the built-in APIs. lastModifiedDateTime isn&#39;t required, but every built-in API has it and any client doing incremental sync will want it.</p><p>ReadIsolation := IsolationLevel::ReadCommitted in OnOpenPage means the API only returns committed data.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4Tg4C_FFQVnhlJY-WuxTGw.png" /><figcaption>The whole endpoint is declared in the object. No Web Services page, no admin step.</figcaption></figure><h3>Finding your endpoint</h3><p>Publish with F5. Nothing visible happens, which is correct. The URL has this shape:</p><pre>http://&lt;container&gt;:7048/BC/api/&lt;publisher&gt;/&lt;group&gt;/&lt;version&gt;/companies({id})/&lt;entitySetName&gt;</pre><p>For our page:</p><pre>http://bcserver:7048/BC/api/albertassaad/projectMgmt/v1.0/companies({id})/projectTasks?tenant=default</pre><p>If you created the container with -updateHostsFile, its name resolves from the host. Otherwise use localhost.</p><p>That ?tenant=default matters more than it looks. BcContainerHelper containers are multitenant, and every web service URL has to name the tenant. It becomes &amp;tenant=default when there&#39;s already a query string. Leave it off and you don&#39;t get a tenant error. You get Authentication_InvalidCredentials, a 401 that sends you off checking passwords and regenerating keys when the credentials were never the problem. It stays on every URL in this article for that reason. If your container is single-tenant, drop it.</p><h3>Getting a credential the API accepts</h3><p>A container created with -auth NavUserPassword accepts basic auth, but not with your login password. On-premises, web service calls authenticate with the user&#39;s <strong>Web Service Access Key</strong>, a 44-character string on the user account. It depends on the URL, not the tool: anything under /api/ or /ODataV4/ wants the key. So a browser that signs you into the web client fine and then rejects you on an API URL is behaving as designed.</p><p>Send the login password and you get:</p><pre>{&quot;error&quot;:{&quot;code&quot;:&quot;Authentication_InvalidCredentials&quot;,&quot;message&quot;:&quot;Web service call failed because user could not be authenticated or authorized.&quot;}}</pre><p>The credentials aren’t wrong. They’re the wrong kind.</p><p>To generate a key:</p><ol><li>Open the web client, signed in as the user you’re generating the key for.</li><li>Open Tell Me, type Users, and pick the <strong>Users</strong> page.</li><li>Click the <strong>ADMIN</strong> row to open the User Card.</li><li>Find the <strong>Web Service Access</strong> section. If it isn’t showing, choose <strong>Show more</strong>, the same trap as the Customer Card in Part 5.</li><li>Click into <strong>Web Service Access Key</strong>. A dialog opens called <strong>Set the Web Service Access Key</strong>.</li><li>Tick <strong>Key Never Expires</strong> and choose <strong>OK</strong>.</li><li>Copy the key now.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XLSh1c27hkE2QSVqote9vA.png" /><figcaption>This string is your API password, not the one you log in with.</figcaption></figure><p>The key is only shown in full to its owner, which is why step 1 matters. Close the page without copying it and the only recovery is a new key, which breaks anything using the old one.</p><p>You can also do it from PowerShell. Generate once:</p><pre>Invoke-ScriptInBcContainer -containerName bcserver -scriptblock {<br>    Set-NAVServerUser -ServerInstance BC -Tenant default -UserName admin -CreateWebServicesKey<br>}</pre><p>Then read it back as often as you like:</p><pre>Invoke-ScriptInBcContainer -containerName bcserver -scriptblock {<br>    Get-NAVServerUser -ServerInstance BC -Tenant default |<br>        Where-Object UserName -eq &#39;ADMIN&#39; |<br>        Select-Object UserName, WebServicesKey<br>}</pre><p>Keep those two separate. -CreateWebServicesKey doesn&#39;t check for an existing key, it just replaces it. Combine generate and read, re-run it later because you forgot the key, and you&#39;ve silently invalidated the one that was working. The symptom is a 401 on a call that worked five minutes ago.</p><p>-Tenant default is needed because the container is multitenant. Without it the cmdlet stops with &quot;A tenant was not specified, but is needed because the system has multiple tenants.&quot; Get-NAVTenant -ServerInstance BC inside the container shows the tenant name if yours isn&#39;t default.</p><p>Basic auth is a local-development convenience. Business Central online uses OAuth 2.0 with an Entra ID app registration, and nothing here carries over to production authentication.</p><h3>Picking something to send requests with</h3><p>Three options, none needing an install:</p><ol><li>Your browser. Fine for GET, but it can’t do POST or PATCH.</li><li>PowerShell, using Invoke-RestMethod. Already on your machine and handles every verb.</li><li>REST Client for VS Code. Requests live in a .http file next to your AL code, and it&#39;s what I use day to day.</li></ol><p>I’m using PowerShell in Windows Terminal because it’s already installed and I’d rather you spend this part on the API than on setting up a tool. Keep one PowerShell tab open until the end; every call goes in that tab. If you’d like a REST Client version as its own part, tell me in the comments.</p><p>Build the auth header once:</p><pre>$user = &#39;admin&#39;<br>$key  = &#39;paste-your-44-character-key-here&#39;<br>$pair = &quot;$($user):$($key)&quot;<br>$b64  = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))<br>$headers = @{ Authorization = &quot;Basic $b64&quot; }</pre><p>Replace the placeholder with your key, or you get a 401 identical to every other 401. The block prints nothing, and that’s success. $headers only exists in this PowerShell session. Open a new window and the header goes out blank.</p><h3>Finding the company id</h3><p>Every API URL needs the company’s GUID. The standard API route lists them:</p><pre>Invoke-RestMethod -Uri &quot;http://bcserver:7048/BC/api/v2.0/companies?tenant=default&quot; -Headers $headers |<br>    Select-Object -ExpandProperty value |<br>    Select-Object id, name</pre><p>The raw response looks like this, trimmed to the company we want:</p><pre>{<br>  &quot;@odata.context&quot;: &quot;http://bcserver:7048/BC/api/v2.0/$metadata#companies&quot;,<br>  &quot;value&quot;: [<br>    {<br>      &quot;id&quot;: &quot;3bfa1827-5ca4-f111-90df-6045bdfb87b0&quot;,<br>      &quot;name&quot;: &quot;CRONUS International Ltd.&quot;,<br>      &quot;displayName&quot;: &quot;CRONUS International Ltd.&quot;<br>    }<br>  ]<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JrKvGJSW7HKvMHLgvyYWYw.png" /><figcaption>This GUID goes into every URL from here on. Save it in a variable now.</figcaption></figure><p>A 200 here also proves the key works and the API stack is running.</p><p>You may get two companies: CRONUS and an empty one called My Company. Use CRONUS, since that’s where your Part 4 tasks live. Put its id in a variable with the base URL:</p><pre>$company = &#39;3bfa1827-5ca4-f111-90df-6045bdfb87b0&#39;<br>$base = &quot;http://bcserver:7048/BC/api/albertassaad/projectMgmt/v1.0/companies($company)&quot;</pre><h3>Checking the endpoint exists</h3><p>Before reading data, ask for the metadata:</p><pre>$url = &#39;http://bcserver:7048/BC/api/albertassaad/projectMgmt/v1.0/$metadata?tenant=default&#39;<br>(Invoke-WebRequest -Uri $url -Headers $headers -UseBasicParsing).Content</pre><p>Three details in that line are deliberate:</p><ol><li>Single quotes. In double quotes PowerShell treats $metadata as an empty variable, and you quietly get the route root instead.</li><li>Invoke-WebRequest, because the response is XML and we want the raw text.</li><li>-UseBasicParsing. Without it, Windows PowerShell 5.1 stops and asks this on every call, not once per session:</li></ol><pre>Security Warning: Script Execution Risk<br>Invoke-WebRequest parses the content of the web page. Script code in the web page<br>might be run when the page is parsed.<br>      RECOMMENDED ACTION:<br>      Use the -UseBasicParsing switch to avoid script code execution.<br>      Do you want to continue?<br>[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is &quot;N&quot;):</pre><p>An EDMX document with a projectTask entity type means the page is live. A 404 means the URL is wrong; a 405 means the API stack is off.</p><p>It’s worth reading, because it shows things the AL doesn’t:</p><pre>&lt;EnumType Name=&quot;projectTaskStatus&quot;&gt;<br>  &lt;Member Name=&quot;Open&quot; Value=&quot;0&quot;/&gt;<br>  &lt;Member Name=&quot;In_x0020_Progress&quot; Value=&quot;1&quot;/&gt;<br>  &lt;Member Name=&quot;Completed&quot; Value=&quot;2&quot;/&gt;<br>&lt;/EnumType&gt;</pre><p>In Part 4 we wrote value(1; &quot;In Progress&quot;). A space isn&#39;t legal in an OData enum member name, so the platform encoded it as _x0020_. Filters have to send In_x0020_Progress, not In Progress. Nothing is broken, but once an object is on HTTP its names stop being internal. If I wrote Part 4 again, I&#39;d name the value InProgress and put the space in the caption.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kgwMu8X220cjHZNSY_fXVg.png" /><figcaption>The metadata document is the source of truth for field names and enum values. Read it before you write a filter.</figcaption></figure><h3>Reading and writing</h3><p>Start with a GET on the collection:</p><pre>Invoke-RestMethod -Uri &quot;$base/projectTasks?tenant=default&quot; -Headers $headers |<br>    Select-Object -ExpandProperty value</pre><p>Invoke-RestMethod turns the JSON into PowerShell objects, so each task prints as a block of properties. The JSON behind each one has this shape:</p><pre>{<br>  &quot;value&quot;: [<br>    {<br>      &quot;@odata.etag&quot;: &quot;W/\&quot;JzIwOzE1NTU5NDM4NzM5NTE0NjM1NTQ5MTswMDsn\&quot;&quot;,<br>      &quot;id&quot;: &quot;5f0b0e4e-1c8f-ee11-9d24-6045bd8f0c3b&quot;,<br>      &quot;number&quot;: &quot;TASK001&quot;,<br>      &quot;description&quot;: &quot;Migrate the reporting server&quot;,<br>      &quot;status&quot;: &quot;Open&quot;,<br>      &quot;dueDate&quot;: &quot;2026-11-20&quot;,<br>      &quot;completedOn&quot;: &quot;0001-01-01&quot;,<br>      &quot;lastModifiedDateTime&quot;: &quot;2026-09-01T08:14:22.61Z&quot;<br>    }<br>  ]<br>}</pre><p>completedOn comes back as 0001-01-01, not null, because a blank AL Date serializes that way. Your client has to treat it as empty. And @odata.etag comes back in the PATCH section.</p><p>Query options join the URL with &amp;, since tenant=default already took the ?:</p><pre>$filter=status eq &#39;Open&#39;<br>$filter=status eq &#39;In_x0020_Progress&#39;<br>$filter=dueDate lt 2026-12-01<br>$select=number,description,status<br>$orderby=dueDate<br>$top=10</pre><p>The second line is the encoded enum member from the metadata. In PowerShell, put a backtick before the $, or $filter is read as an empty variable and your filter silently disappears:</p><pre>Invoke-RestMethod -Uri &quot;$base/projectTasks?tenant=default&amp;`$filter=status eq &#39;Open&#39;&quot; -Headers $headers |<br>    Select-Object -ExpandProperty value</pre><p>Any line from the list works the same way after the &amp;.</p><p>Creating a task is a POST to the collection. Build the body as a hashtable and let ConvertTo-Json produce the JSON:</p><pre>$body = @{<br>    number      = &#39;TASK002&#39;<br>    description = &#39;Rebuild the nightly export&#39;<br>    status      = &#39;Open&#39;<br>    dueDate     = &#39;2026-11-15&#39;<br>} | ConvertTo-Json<br><br>Invoke-RestMethod -Uri &quot;$base/projectTasks?tenant=default&quot; -Headers $headers `<br>    -Method Post -Body $body -ContentType &#39;application/json&#39;</pre><p>Without -ContentType &#39;application/json&#39;, PowerShell sends form data and the API refuses it. A successful POST returns the new record with its id.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DL-FwqyKs0yLnLoVFfnErA.png" /></figure><p>Don’t send id or completedOn: the platform assigns one, and our business logic owns the other.</p><p>The date is November for a reason. Post an October date to a CRONUS demo container and you get:</p><pre>{&quot;error&quot;:{&quot;code&quot;:&quot;Internal_DataNotFoundFilter&quot;,&quot;message&quot;:&quot;In the current company the date you&#39;ve entered is outside the allowed interval (this is determined by the filter &#39;??11*|??12*|??01*|??02*&#39;, which is defined by the license file).&quot;,&quot;target&quot;:&quot;dueDate&quot;}}</pre><p>The demo licence only allows November to February. That’s annoying, but it taught me something: the API isn’t a side door. Your POST ran the same validation, triggers and licence checks as a user typing into the card. If the client refuses a value, so does the API.</p><p>The new record shows up in the Project Task List like any other.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fLYXHGmRXZXdUDrquTyGmg.png" /><figcaption>Created over HTTP, sitting in the client like any other record.</figcaption></figure><h3>Updating, and the etag rule</h3><p>A PATCH goes to the single-record URL, keyed by the GUID, and needs an If-Match header with the record&#39;s current @odata.etag. Take both from the record rather than copying by hand:</p><pre>$task = Invoke-RestMethod -Uri &quot;$base/projectTasks?tenant=default&amp;`$filter=number eq &#39;TASK002&#39;&quot; -Headers $headers |<br>    Select-Object -ExpandProperty value<br><br>$id   = $task.id<br>$etag = $task.&#39;@odata.etag&#39;<br><br>$body = @{ description = &#39;Rebuild the nightly export (revised)&#39; } | ConvertTo-Json<br><br>Invoke-RestMethod -Uri &quot;$base/projectTasks($id)?tenant=default&quot; `<br>    -Headers ($headers + @{ &#39;If-Match&#39; = $etag }) `<br>    -Method Patch -Body $body -ContentType &#39;application/json&#39;</pre><p>PATCH merges, so you only send what changes. A GUID that doesn’t exist returns:</p><pre>{&quot;error&quot;:{&quot;code&quot;:&quot;BadRequest_ResourceNotFound&quot;,&quot;message&quot;:&quot;Resource not found for the segment &#39;projectTask&#39;.&quot;}}</pre><p>It reads like a routing problem, but it means the collection was found and the record wasn’t.</p><h3>Why the etag matters</h3><p>If someone changed the record between your GET and your PATCH, your etag no longer matches and the server answers 412 Precondition Failed instead of overwriting their edit. That’s optimistic concurrency, and API pages have it on by default.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PyjKZqRFkzQhaOt3NpdJag.png" /><figcaption>A stale etag. This is the error protecting you, not fighting you.</figcaption></figure><p>If-Match: * skips the check. Fine for a throwaway test, a bad habit otherwise.</p><h3>Calling AL logic over HTTP with a bound action</h3><p>Everything so far is CRUD. But in Part 4, codeunit 50124’s CompleteTask sets the status and stamps today&#39;s date, and an external system shouldn&#39;t need to know those steps. It should say &quot;complete this task&quot; and let Business Central decide what that means.</p><p>That’s a bound action: a procedure on the API page marked [ServiceEnabled], callable by POST on a single record.</p><p>Where the procedure goes matters, and it’s easy to get wrong the first time. It belongs to the page, not to the page’s layout. Open Pag50200.ProjectTasksAPI.al, scroll to the bottom, and put it:</p><ol><li>After the closing brace of the layout section.</li><li>Before the page’s final closing brace.</li></ol><p>Paste it inside area(Content) or the repeater and the compiler rejects it, because those blocks only accept controls. The OnOpenPage trigger already sits in the right spot, so I put the procedure straight after it. Here&#39;s the bottom of the page once it&#39;s in:</p><pre>    layout<br>    {<br>        area(Content)<br>        {<br>            repeater(Group)<br>            {<br>                // the fields from earlier: id, number, description ...<br>            }<br>        }<br>    }<br><br>    trigger OnOpenPage()<br>    begin<br>        Rec.ReadIsolation := IsolationLevel::ReadCommitted;<br>    end;<br><br>    [ServiceEnabled]<br>    procedure completeTask(var ActionContext: WebServiceActionContext)<br>    var<br>        ProjectTask: Record &quot;Project Task&quot;;<br>        ProjectTaskMgt: Codeunit &quot;Project Task Mgt.&quot;;<br>    begin<br>        ProjectTask.GetBySystemId(Rec.SystemId);<br>        ProjectTaskMgt.CompleteTask(ProjectTask);<br><br>        ActionContext.SetObjectType(ObjectType::Page);<br>        ActionContext.SetObjectId(Page::&quot;Project Tasks API&quot;);<br>        ActionContext.AddEntityKey(Rec.FieldNo(SystemId), ProjectTask.SystemId);<br>        ActionContext.SetResultCode(WebServiceActionResultCode::Updated);<br>    end;<br>}</pre><p>That last brace closes the page. If you end up with two of them after the procedure, one of them is left over from where you pasted.</p><p>Codeunit 50124 comes from the Part 4 app, the same way the Project Task table does. The dependency we declared at the start is what lets this page see it, so nothing new goes into app.json.</p><p>The procedure doesn’t set the status or work out the date. It hands the record to the same codeunit the Complete Task button calls. One rule, two entry points: change the codeunit and both get the new behavior. The ActionContext lines tell the caller which record changed and how (Updated here, Created if the procedure had made something).</p><p>Bound actions are invoked as Microsoft.NAV.&lt;procedureName&gt;, matching the procedure&#39;s case exactly. That&#39;s why it&#39;s completeTask in camelCase: its name becomes part of a public URL.</p><p>Republish. $id still holds TASK002 from the PATCH, the task we created over HTTP, so it can finish its short life properly. Run $id first and make sure a GUID prints. An empty $id builds a URL ending in projectTasks(), which Business Central reads as the whole collection, and the 404 complains about collection segments rather than the empty variable.</p><pre>$callUrl = &quot;$base/projectTasks($id)/Microsoft.NAV.completeTask?tenant=default&quot;<br><br>$response = Invoke-WebRequest -Uri $callUrl -Headers $headers -Method Post -UseBasicParsing<br>$response.StatusCode</pre><p>Invoke-WebRequest again, because the response has no body and $response.StatusCode is the only acknowledgement. On my container it prints 200 with an empty body, though Microsoft documents 204 for some bound actions, so check for any success code rather than one number. No request body either: the URL names the record and the codeunit does the rest.</p><p>GET TASK002 back:</p><pre>Invoke-RestMethod -Uri &quot;$base/projectTasks($id)?tenant=default&quot; -Headers $headers |<br>    Select-Object number, status, completedOn</pre><p>Status is Completed and completedOn holds today’s date, exactly as if someone had clicked the button on the card page. We never sent either value.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O0mWwuF_0JprKwOAJgCanw.png" /><figcaption>No body sent, no body returned. The work happened in AL.</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0wqcrx3EXnZ5c0p6ihLNHQ.png" /><figcaption>Same result as clicking the button in Part 4, triggered from outside Business Central.</figcaption></figure><h3>Wrapping up</h3><p>We took a table that only existed inside Business Central and put it on the network. Most of this part went on the traps around the page rather than the page itself: the dependency, the tenant parameter and the access key.</p><p>The pattern worth carrying forward is the last one. The API page exposes data; the bound action exposes a decision. Keeping the decision in a codeunit means the UI and the integration can never drift apart.</p><p>The code is on GitHub in a new repo, <a href="https://github.com/AlbertAssaad/ProjectTaskApi">ProjectTaskApi</a>. You’ll need the <a href="https://github.com/AlbertAssaad/TaskProject">TaskProject </a>repo from Part 4 to build it.</p><p>In Part 7 we go the other direction: Business Central calling out. HttpClient, JSON handling in AL, and what to do when the service on the other end is slow or down.</p><h4>References</h4><p>API page type — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-api-pagetype">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-api-pagetype</a></p><p>Developing a custom API — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api</a></p><p>App identity — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-app-identity">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-app-identity</a></p><p>JSON files (app.json settings, including dependencies) — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-json-files">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-json-files</a></p><p>Enabling the APIs for Business Central — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/api-reference/v2.0/enabling-apis-for-dynamics-nav">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/api-reference/v2.0/enabling-apis-for-dynamics-nav</a></p><p>Web services authentication (web service access keys) — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/web-services-authentication">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/web-services-authentication</a></p><p>Business Central web services (including the tenant parameter) — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/web-services">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/web-services</a></p><p>API endpoint structure — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/api-endpoint-structure">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/webservices/api-endpoint-structure</a></p><p>Creating and interacting with an OData V4 bound action — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-bound-action">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-creating-and-interacting-with-odatav4-bound-action</a></p><p>System fields (SystemId and the data audit fields) — <a href="https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-table-system-fields">https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-table-system-fields</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8da530048da2" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AL Development in Business Central Part 5: Table Extensions, Page Extensions, and Events]]></title>
            <link>https://albertassaad.medium.com/al-development-in-business-central-part-5-table-extensions-page-extensions-and-events-4a1c535c60c5?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/4a1c535c60c5</guid>
            <category><![CDATA[erp-software]]></category>
            <category><![CDATA[al-programming]]></category>
            <category><![CDATA[business-central]]></category>
            <category><![CDATA[dynamics-365]]></category>
            <category><![CDATA[microsoft]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Fri, 17 Jul 2026 13:20:40 GMT</pubDate>
            <atom:updated>2026-07-17T13:20:40.530Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z8KXNiBW8BaVXAbR25gi1w.png" /></figure><p>In <a href="https://medium.com/@albertassaad/building-your-first-real-al-objects-tables-pages-and-a-codeunit-in-business-central-4e1bfe3823f9">Part 4</a> we built our own objects from scratch: a Project Task table, a list page, a card page, an enum for status, and a codeunit with a Complete Task action. Everything lived in our own ID range and nothing touched Microsoft’s code.<br>That changes today. In this part we’re going to modify Microsoft’s objects. We’ll add a field to the Customer table, surface it on the Customer Card, and then get into events and subscribers, which is the pattern that lets your extension react to what the base application does without ever editing it.</p><p>If you’re just joining the series:</p><ul><li>Part 1: <a href="https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6">https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6</a></li><li>Part 2: <a href="https://albertassaad.medium.com/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0">https://albertassaad.medium.com/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0</a></li><li>Part 3: <a href="https://medium.com/@albertassaad/publishing-al-extensions-to-a-local-business-central-container-using-visual-studio-code-152322bfe181">https://medium.com/@albertassaad/publishing-al-extensions-to-a-local-business-central-container-using-visual-studio-code-152322bfe181</a></li><li>Part 4: <a href="https://medium.com/@albertassaad/building-your-first-real-al-objects-tables-pages-and-a-codeunit-in-business-central-4e1bfe3823f9">https://medium.com/@albertassaad/building-your-first-real-al-objects-tables-pages-and-a-codeunit-in-business-central-4e1bfe3823f9</a></li></ul><p>The code for this part lives in a new repo: <a href="https://github.com/AlbertAssaad/CustomerExtension">https://github.com/AlbertAssaad/CustomerExtension</a></p><h3>1- A new project, a new repo, a new ID range</h3><p>I decided not to add this code to the TaskProject repo. This part is about a different concept (extending Microsoft’s objects instead of creating your own), so it gets its own app and its own repo. It also gives us a chance to walk through starting a second AL project, which raises a question that will bite you sooner or later: can two extensions on the same container use the same object IDs? No, they can’t. Object IDs must be unique across everything installed in the environment, not just within one app. TaskProject already owns 50100 to 50149, and both apps will be published to the same Docker container, so this new app gets the next block. My app.json:</p><pre>{<br>  &quot;id&quot;: &quot;cb525349-c37a-4d37-a1ab-ef41ea5d4b3a&quot;,<br>  &quot;name&quot;: &quot;CustomerExtension&quot;,<br>  &quot;publisher&quot;: &quot;Albert Assaad&quot;,<br>  &quot;version&quot;: &quot;1.0.0.0&quot;,<br>  &quot;application&quot;: &quot;28.0.0.0&quot;,<br>  &quot;runtime&quot;: &quot;17.0&quot;,<br>  &quot;idRanges&quot;: [<br>    {<br>      &quot;from&quot;: 50150,<br>      &quot;to&quot;: 50199<br>    }<br>  ],<br>  &quot;features&quot;: [<br>    &quot;NoImplicitWith&quot;<br>  ]<br>}</pre><h3>a- Setting up the project step by step</h3><p>If you followed Parts 2 and 3 this will feel familiar, but since it’s a brand new project, here’s the exact sequence I used.</p><p>Before anything else, it helps to understand what an AL project actually is: just a folder. There’s no “New Project” wizard like in Visual Studio, no solution file, no project file. VS Code opens a folder, and if that folder contains an app.json, the AL extension treats it as an AL project. That&#39;s the whole mechanism. So creating a new project means creating a new folder and letting AL: Go! fill it.</p><ol><li>Create an empty folder called CustomerExtension. Where you put it is up to you; mine sits next to the TaskProject folder so both projects live in one place. You can create it in File Explorer or from a terminal with mkdir CustomerExtension.</li><li>Open the folder in VS Code: File, then Open Folder, and select CustomerExtension. Don&#39;t just open the parent directory that contains both projects; the AL extension expects one project per workspace, and opening the parent confuses it. If VS Code asks whether you trust the authors of this folder, say yes, it&#39;s your own empty folder.</li><li>Confirm the AL Language extension is active. It’s the one we installed in <a href="https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6">Part </a>1 from the VSIX at http://bcserver:8080/ALLanguage.vsix, so if you&#39;ve been following along it&#39;s already there. You can check under the Extensions panel (Ctrl+Shift+X); you should see &quot;AL Language&quot; installed. A quicker test: press Ctrl+Shift+P and type &quot;AL:&quot;. If you see a list of AL commands, you&#39;re good.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zmNHTJvkcl5m9c3CCcN9FQ.png" /></figure><p>4. Press Ctrl+Shift+P and run AL: Go!. Pick the newest target platform when prompted, and choose &quot;Your own server&quot;, not the Microsoft cloud sandbox. This generates app.json, launch.json, and a HelloWorld.al.</p><p>5. Point launch.json at the same Docker container from Part 1:</p><pre>{<br>  &quot;server&quot;: &quot;http://bcserver&quot;,<br>  &quot;serverInstance&quot;: &quot;BC&quot;,<br>  &quot;authentication&quot;: &quot;UserPassword&quot;,<br>  &quot;startupObjectId&quot;: 21,<br>  &quot;startupObjectType&quot;: &quot;Page&quot;<br>}</pre><p>I set startupObjectId to 21, which is the Customer Card. Since that&#39;s the page we&#39;re extending, F5 will drop us straight onto it every time we publish.</p><p>6. Fix app.json before doing anything else. Keep the generated id GUID, set a real name and publisher, and set the ID range to 50150 to 50199. Part 4&#39;s app still says &quot;Default Publisher&quot; in Extension Management, which looks sloppy, so I filled it in properly this time. And I picked the ID range before writing any code instead of fixing collisions afterwards.</p><p>7. Delete HelloWorld.al.</p><p>8. Press Ctrl+Shift+P and run AL: Download symbols, then enter the container credentials. Wait for the .alpackages folder to fill up; nothing compiles before this finishes.</p><p>One ordering tip: do step 6 before step 8. If you download symbols first and then change app.json, you sometimes need to reload the VS Code window before the compiler picks up the new ID range.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*P4zJvxQOw4MDdN-L5Temig.png" /></figure><h3>2- Why you can’t just edit the Customer table</h3><p>If you come from older NAV versions (or from other ERPs), your first instinct might be to open table 18 Customer and add a field to it. In Business Central you can’t, and that’s a good thing.</p><p>Base application objects are read-only. The only way to change them is through extension objects: a tableextension adds fields to an existing table, a pageextension adds controls and actions to an existing page. Your changes live in your app, Microsoft’s code stays untouched, and when Microsoft ships a new BC version your customization survives the upgrade because there’s nothing to merge.</p><p>The mental model is simple: you never change their objects, you attach to them.</p><h3>3- Adding a field to the Customer table</h3><p>Let’s say we want to store a task contact on each customer: the person we coordinate project work with. That’s one new field on table 18.</p><h3>a- The tableextension</h3><p>Create a new file TabExt50150.CustomerTaskExt.al:</p><pre>tableextension 50150 &quot;Customer Task Ext&quot; extends Customer<br>{<br>    fields<br>    {<br>        field(50150; &quot;Task Contact&quot;; Text[100])<br>        {<br>            Caption = &#39;Task Contact&#39;;<br>            DataClassification = CustomerContent;<br>        }<br>    }<br>}</pre><p>Also note DataClassification = CustomerContent. In Part 4 I left the Project Task table at ToBeClassified, which is fine for a demo, but a contact name on a customer record is clearly customer data, so I classified it properly here.</p><h3>4- Showing the field on the Customer Card</h3><p>The field now exists in the database, but no user can see it. Fields don’t appear on pages automatically; that’s what the pageextension is for.</p><h3>a- The pageextension</h3><p>Create PagExt50151.CustomerCardTaskExt.al:</p><pre>pageextension 50151 &quot;Customer Card Task Ext&quot; extends &quot;Customer Card&quot;<br>{<br>    layout<br>    {<br>        addlast(General)<br>        {<br>            field(&quot;Task Contact&quot;; Rec.&quot;Task Contact&quot;)<br>            {<br>                ApplicationArea = All;<br>                ToolTip = &#39;Specifies the contact person for project tasks.&#39;;<br>                Importance = Promoted;<br>            }<br>        }<br>    }<br>}</pre><p>The addlast(General) line is the anchor: it says &quot;put this field at the end of the group named General on the Customer Card&quot;. You can also use addfirst, addafter(SomeControl) and addbefore(SomeControl). The name you anchor to is the control&#39;s name in the page source, not the caption you see in the UI. If you guess wrong, the compiler tells you the control wasn&#39;t found on the target page.</p><p>How do you find the real control names? Open the base page source. In VS Code, put the cursor on &quot;Customer Card&quot;, press F12 (Go to Definition), and you can browse Microsoft&#39;s page code directly from the downloaded symbols. This is one of the most useful habits you can build as an AL developer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ey8MBX9qCix_SiT4F2SNwg.png" /></figure><h3>b- The field that wasn’t there</h3><p>I published the extension (F5, same flow as Part 4), opened a customer, and the field was nowhere on the card. No error, no warning. I spent a few minutes doubting the pageextension before I found it: the field was there all along, hidden behind the “Show more” link on the General group.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fTjd7eJ4iCmCXbRwOsM85g.png" /></figure><p>Business Central pages collapse less important fields by default, and a freshly added field can land in the collapsed section. That’s what the Importance = Promoted property in the code above fixes: it tells the page this field belongs in the always-visible part of the group. I added it after the fact, republished, and the field showed up directly on the card.</p><p>If you ever publish a pageextension and “nothing happened”, check Show more before you start debugging.</p><h3>5- Events and subscribers</h3><p>So far our extensions add things: fields, controls. Events let them react to things. This is the pattern that makes AL extensions production-grade, because it replaces the old NAV habit of writing code inside base application triggers.</p><h3>a- How the pattern works</h3><p>There are two roles:</p><ol><li>A publisher declares an event: “something happened here, anyone interested?” Base application code is full of these, and every table and page also raises built-in trigger events like OnBeforeInsertEvent and OnAfterModifyEvent.</li><li>A subscriber is a procedure in your codeunit decorated with an [EventSubscriber] attribute. When the event fires, the platform calls your procedure. The publisher has no idea you exist.</li></ol><p>That last sentence is the whole point. The base app doesn’t reference your code, so your code can’t break the base app, and upgrades stay clean.</p><h3>b- Subscribing to a base application event</h3><p>Let’s put a small rule on our new field: when a customer gets a name and no task contact was entered, default the task contact to that name. My first attempt was the obvious one, subscribing to the insert event:</p><pre>codeunit 50153 &quot;Customer Task Events&quot;<br>{<br>    [EventSubscriber(ObjectType::Table, Database::Customer, OnBeforeInsertEvent, &#39;&#39;, false, false)]<br>    local procedure DefaultTaskContactOnBeforeInsertCustomer(var Rec: Record Customer; RunTrigger: Boolean)<br>    begin<br>        if Rec.&quot;Task Contact&quot; = &#39;&#39; then<br>            Rec.&quot;Task Contact&quot; := Rec.Name;<br>    end;<br>}</pre><p>This compiles, publishes, and does nothing useful. I created a new customer, typed the name, reopened the card: Task Contact was empty.</p><p>The subscriber wasn’t broken; my timing was. When you click New on a card page, Business Central inserts the record almost immediately: the number series assigns the No. and the insert happens before you’ve typed a single character. So OnBeforeInsertEvent fired at a moment when Name was still empty, faithfully copied that empty name into Task Contact, and everything I typed afterwards was a Modify, which this subscriber ignores. If you&#39;ve ever wondered why a new customer already has a No. before you&#39;ve filled anything in, this is the same mechanism.</p><p>The fix is to react to the moment the name actually arrives, which is the validation of the Name field. Here’s the corrected Cod50153.CustomerTaskEvents.al:</p><pre>codeunit 50153 &quot;Customer Task Events&quot;<br>{<br>    [EventSubscriber(ObjectType::Table, Database::Customer, OnAfterValidateEvent, Name, false, false)]<br>    local procedure DefaultTaskContactOnValidateCustomerName(var Rec: Record Customer; var xRec: Record Customer; CurrFieldNo: Integer)<br>    begin<br>        if Rec.&quot;Task Contact&quot; = &#39;&#39; then<br>            Rec.&quot;Task Contact&quot; := Rec.Name;<br>    end;<br>}</pre><p>Reading the attribute left to right: we subscribe to a table event, on the Customer table, specifically OnAfterValidateEvent, for the Name field. That fourth parameter is the field filter: table validate events exist per field, and this is where you say which one you want. For events that don’t target a specific field, like the insert event above, it stays an empty string. The last two booleans control skipping on missing license and manual binding; false, false is what you want in almost every case.</p><p>Now the flow works with the UI instead of against it: you type the name, the page validates the field, our subscriber fills Task Contact while the record is still in memory, and the page’s own save persists it. No extra Modify call needed.</p><p>Two things this little failure teaches. First, subscribing to the technically correct event is not the same as subscribing to the right moment; you have to know when base application code actually runs. Second, a subscriber that never fires (or fires too early) fails in complete silence. When that happens, set a breakpoint inside the subscriber and walk through the UI flow; you’ll see immediately whether it fires and what the record looks like when it does.</p><p>Is defaulting a contact to the customer name a great business rule? Honestly, no. It’s a demo rule. The wiring is what matters here.</p><h3>c- Publishing your own event</h3><p>Subscribing to Microsoft’s events is half the story. You can also publish events from your own code, so other code (yours, a colleague’s, another extension entirely) can hook into it without touching it.</p><p>Let’s give our extension one real operation: assigning a task contact through a codeunit instead of typing it into the field. Create Cod50152.CustomerTaskMgt.al:</p><pre>codeunit 50152 &quot;Customer Task Mgt.&quot;<br>{<br>    procedure AssignTaskContact(var Customer: Record Customer; NewContact: Text[100])<br>    begin<br>        Customer.&quot;Task Contact&quot; := NewContact;<br>        Customer.Modify(true);<br>        OnAfterAssignTaskContact(Customer);<br>    end;<br><br>    [IntegrationEvent(false, false)]<br>    local procedure OnAfterAssignTaskContact(var Customer: Record Customer)<br>    begin<br>    end;<br>}</pre><p>The event procedure is empty on purpose. It’s a declaration, not an implementation: “at this point, a task contact was assigned, here’s the customer”. Anyone can subscribe to it. This is exactly how Microsoft structures the base application, and if you browse base app code with Go to Definition you’ll find OnBefore and OnAfter integration events around almost every meaningful operation.</p><p>To make the operation reachable from the UI, we extend the pageextension from section 4 with an action. Pageextensions can add actions the same way they add fields:</p><pre>actions<br>    {<br>        addlast(Processing)<br>        {<br>            action(AssignTaskContact)<br>            {<br>                ApplicationArea = All;<br>                Caption = &#39;Assign Task Contact&#39;;<br>                Image = ContactPerson;<br>                ToolTip = &#39;Sets the task contact to the customer&#39;&#39;s main contact.&#39;;<br><br>                trigger OnAction()<br>                var<br>                    CustomerTaskMgt: Codeunit &quot;Customer Task Mgt.&quot;;<br>                begin<br>                    CustomerTaskMgt.AssignTaskContact(Rec, Rec.Contact);<br>                    CurrPage.Update(false);<br>                end;<br>            }<br>        }<br>    }</pre><p>This action copies the customer’s main Contact into our Task Contact field. Again, a demo operation, but notice the shape: the page action only calls the codeunit, the codeunit does the work and raises the event. Same layering we used for Complete Task in Part 4.</p><h3>d- Subscribing to our own event</h3><p>Now add a second subscriber to codeunit 50153:</p><pre>[EventSubscriber(ObjectType::Codeunit, Codeunit::&quot;Customer Task Mgt.&quot;, OnAfterAssignTaskContact, &#39;&#39;, false, false)]<br>    local procedure NotifyOnTaskContactAssigned(var Customer: Record Customer)<br>    begin<br>        Message(&#39;Task contact for %1 is now %2.&#39;, Customer.&quot;No.&quot;, Customer.&quot;Task Contact&quot;);<br>    end;</pre><p>One thing to be careful with: the subscriber’s parameters must match the event’s signature. If they don’t, the compiler catches it when you reference the event by identifier like we do here. In older code you’ll see event names as strings in the attribute; avoid that style, because a typo in a string compiles fine and your subscriber just never fires. Nothing tells you. Identifier-based references turn that silent failure into a compile error.</p><h3>6- Testing it</h3><p>Publish with F5 and try both paths:</p><ol><li>Create a new customer and type a name. As soon as you leave the Name field, Task Contact fills in with the same value. That’s our OnAfterValidateEvent subscriber firing on the Name validation.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*89hBEZ1kCRpLZZx7MRHCpw.png" /></figure><p>2. Open a customer that has a Contact filled in and run the Assign Task Contact action. The field updates, and a message pops up: “Task contact for 10000 is now …”. That message comes from a subscriber codeunit that Customer Task Mgt. knows nothing about.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4i1FuoMPizxt8pMrdvk97g.png" /></figure><p>The message is obviously a placeholder. In a real project that subscriber might send a notification, write to an activity log, or update a related record. The structure stays the same.</p><p>Both apps now live side by side on the container: TaskProject with its Project Task objects, CustomerExtension with these. Open Extension Management (search for it with Alt+Q) and you’ll see them listed separately.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jOdqpfUFEkkPCQ2WyN3NNg.png" /></figure><h3>Wrapping up</h3><p>Object inventory for this new app:</p><ul><li>TableExtension 50150 “Customer Task Ext”</li><li>PageExtension 50151 “Customer Card Task Ext”</li><li>Codeunit 50152 “Customer Task Mgt.”</li><li>Codeunit 50153 “Customer Task Events”</li></ul><p>We covered starting a second AL project with its own ID range (and why the ranges must not overlap), the two extension objects you’ll use constantly (tableextension and pageextension), the Show more trap, adding actions through a pageextension, and both sides of the event pattern: subscribing to base application events and publishing your own.</p><p>In Part 6 I’m planning to open the Project Task data from Part 4 to the outside world: an API page over our table, queried through OData, which connects this series back to the integration work I usually write about.</p><p>The code for this part: <a href="https://github.com/AlbertAssaad/CustomerExtension">https://github.com/AlbertAssaad/CustomerExtension</a></p><p>Questions or corrections are welcome in the comments. If you hit an error I didn’t cover, post it; the errors are half the value of this series.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4a1c535c60c5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building Your First Real AL Objects: Tables, Pages, and a Codeunit in Business Central]]></title>
            <link>https://albertassaad.medium.com/building-your-first-real-al-objects-tables-pages-and-a-codeunit-in-business-central-4e1bfe3823f9?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/4e1bfe3823f9</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[dynamics-365]]></category>
            <category><![CDATA[business-central]]></category>
            <category><![CDATA[microsoft-dynamics-nav]]></category>
            <category><![CDATA[microsoft]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Mon, 06 Jul 2026 06:53:49 GMT</pubDate>
            <atom:updated>2026-07-06T06:53:49.130Z</atom:updated>
            <content:encoded><![CDATA[<p>In <a href="https://medium.com/@albertassaad/publishing-al-extensions-to-a-local-business-central-container-using-visual-studio-code-152322bfe181?sharedUserId=albertassaad">Part 3</a> I published an empty extension to the local bcserver container just to prove the pipeline worked. It compiled, it deployed, and it did absolutely nothing. This time we fix that.</p><p>By the end of this part you’ll have a table that stores data, a list page to browse it, a card page to create and edit records, and an action button backed by a codeunit that actually changes a record. You’ll find all of it running inside your container, searchable from Tell Me, like any other BC page.</p><p>I’m building a small “Project Task” object because it’s just enough to touch every concept without turning into a tutorial about project management. Swap the fields for whatever fits your own head.</p><h3>1- The Table</h3><p>A table is where the data lives. Everything else in this part points back to it.</p><p>Create a new file in your AL project. I name table files Tab&lt;ID&gt;.&lt;Name&gt;.al, so this one is Tab50120.ProjectTask.al. The object ID 50120 sits inside the free range (50000–99999) that Microsoft leaves open for per-tenant extensions. Pick an ID that no other app in your container already uses, since BC won&#39;t let two apps define a table with the same ID.</p><pre>table 50120 &quot;Project Task&quot;<br>{<br>    DataClassification = ToBeClassified;<br><br>    fields<br>    {<br>        field(1; &quot;No.&quot;; Code[20])<br>        {<br>            Caption = &#39;No.&#39;;<br>        }<br>        field(2; Description; Text[100])<br>        {<br>            Caption = &#39;Description&#39;;<br>        }<br>        field(3; Status; Enum &quot;Project Task Status&quot;)<br>        {<br>            Caption = &#39;Status&#39;;<br>        }<br>        field(4; &quot;Due Date&quot;; Date)<br>        {<br>            Caption = &#39;Due Date&#39;;<br>        }<br>        field(5; &quot;Completed On&quot;; Date)<br>        {<br>            Caption = &#39;Completed On&#39;;<br>            Editable = false;<br>        }<br>    }<br><br>    keys<br>    {<br>        key(PK; &quot;No.&quot;)<br>        {<br>            Clustered = true;<br>        }<br>    }<br>}</pre><p>A few things worth noticing here:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*svDycdYjEp3rq7QsTwcFcg.png" /></figure><p>a- Every field has a numeric ID, a name, and a data type. The IDs only need to be unique within the table.</p><p>b- &quot;No.&quot; is the primary key, defined down in the keys section. Clustered = true tells SQL Server how to physically order the rows.</p><p>c- I used Enum for Status instead of the older Option type. Enums are extensible and the modern recommendation, so let&#39;s build the habit now.</p><p>d- &quot;Completed On&quot; is Editable = false because the user shouldn&#39;t type it. The codeunit in section 4 will set it.</p><p>If you save the table now, it won’t compile. The Status field points at an Enum &quot;Project Task Status&quot; that doesn&#39;t exist yet, so AL throws an error until you create the enum in the next section. That&#39;s expected; don&#39;t try to fix it here.</p><h3>2- The Enum</h3><p>The Status field references an enum that doesn&#39;t exist yet, so the table won&#39;t compile until we create it. Make a file Enum50121.ProjectTaskStatus.al:</p><pre>enum 50121 &quot;Project Task Status&quot;<br>{<br>    Extensible = true;<br><br>    value(0; Open) { Caption = &#39;Open&#39;; }<br>    value(1; &quot;In Progress&quot;) { Caption = &#39;In Progress&#39;; }<br>    value(2; Completed) { Caption = &#39;Completed&#39;; }<br>}</pre><p>Extensible = true means another extension could add its own status values later without editing this file. That&#39;s the whole point of enums over options.</p><h3>3- The Pages</h3><p>A table you can’t see is useless. We need two pages: a list to browse records and a card to edit one at a time.</p><h3>a- The List Page</h3><p>File Pag50122.ProjectTaskList.al:</p><pre>page 50122 &quot;Project Task List&quot;<br>{<br>    PageType = List;<br>    ApplicationArea = All;<br>    UsageCategory = Lists;<br>    SourceTable = &quot;Project Task&quot;;<br>    CardPageId = &quot;Project Task Card&quot;;<br><br>    layout<br>    {<br>        area(Content)<br>        {<br>            repeater(Group)<br>            {<br>                field(&quot;No.&quot;; Rec.&quot;No.&quot;) { ApplicationArea = All; }<br>                field(Description; Rec.Description) { ApplicationArea = All; }<br>                field(Status; Rec.Status) { ApplicationArea = All; }<br>                field(&quot;Due Date&quot;; Rec.&quot;Due Date&quot;) { ApplicationArea = All; }<br>            }<br>        }<br>    }<br>}</pre><p>Two properties make this page findable in the running client:</p><ul><li>UsageCategory = Lists puts the page in the Tell Me search results.</li><li>ApplicationArea = All makes the page and its fields visible regardless of which BC application areas are enabled.</li></ul><p>CardPageId links the list to the card, so double-clicking a row opens it for editing.</p><p>Same situation as the table and enum: this page won’t compile on its own. CardPageId = &quot;Project Task Card&quot; references a card page we haven&#39;t built yet, so AL will flag it until you create the card in the next section. Keep going.</p><h3>b- The Card Page</h3><p>File Pag50123.ProjectTaskCard.al:</p><pre>page 50123 &quot;Project Task Card&quot;<br>{<br>    PageType = Card;<br>    ApplicationArea = All;<br>    SourceTable = &quot;Project Task&quot;;<br><br>    layout<br>    {<br>        area(Content)<br>        {<br>            group(General)<br>            {<br>                field(&quot;No.&quot;; Rec.&quot;No.&quot;) { ApplicationArea = All; }<br>                field(Description; Rec.Description) { ApplicationArea = All; }<br>                field(Status; Rec.Status) { ApplicationArea = All; }<br>                field(&quot;Due Date&quot;; Rec.&quot;Due Date&quot;) { ApplicationArea = All; }<br>                field(&quot;Completed On&quot;; Rec.&quot;Completed On&quot;) { ApplicationArea = All; }<br>            }<br>        }<br>    }<br>}</pre><p>The card has no UsageCategory on purpose. You don&#39;t search for a single card from Tell Me; you reach it through the list.</p><h3>4- The Codeunit and the Action</h3><p>Now for the part that does something. I want a button on the card that marks a task complete: it flips the status to Completed and stamps today&#39;s date into &quot;Completed On&quot;.</p><p>I’ll put the logic in a codeunit rather than directly in the page. Keeping behavior out of the UI is a habit that pays off the moment you want to call the same logic from somewhere else.</p><p>File Cod50124.ProjectTaskMgt.al:</p><pre>codeunit 50124 &quot;Project Task Mgt.&quot;<br>{<br>    procedure CompleteTask(var ProjectTask: Record &quot;Project Task&quot;)<br>    begin<br>        ProjectTask.Status := ProjectTask.Status::Completed;<br>        ProjectTask.&quot;Completed On&quot; := Today();<br>        ProjectTask.Modify(true);<br>    end;<br>}</pre><p>Modify(true) writes the record back to the database, and the true runs the table&#39;s modify triggers and validation. Passing the record var means the codeunit edits the caller&#39;s copy directly.</p><p>Now add the action to the card page. Drop an actions section into Pag50123.ProjectTaskCard.al, right after the layout block closes:</p><pre>actions<br>    {<br>        area(Processing)<br>        {<br>            action(CompleteTask)<br>            {<br>                ApplicationArea = All;<br>                Caption = &#39;Complete Task&#39;;<br>                Image = Completed;<br><br>                trigger OnAction()<br>                var<br>                    ProjectTaskMgt: Codeunit &quot;Project Task Mgt.&quot;;<br>                begin<br>                    ProjectTaskMgt.CompleteTask(Rec);<br>                    CurrPage.Update(false);<br>                end;<br>            }<br>        }<br>    }</pre><p>Walking through the trigger:</p><p>a- ProjectTaskMgt is a variable of the codeunit type, declared in the var block of the trigger.</p><p>b- ProjectTaskMgt.CompleteTask(Rec) passes the page&#39;s current record (Rec) into the procedure.</p><p>c- CurrPage.Update(false) refreshes the page so you see the new status and date without reopening the card. The false means don&#39;t save again; the codeunit already did.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/364/1*qLFwoighfsiE5e8LtkIATg.png" /></figure><p>The full source for this part is on GitHub if you want to compare against your own: <a href="https://github.com/AlbertAssaad/TaskProject">github.com/AlbertAssaad/TaskProject</a>.</p><h3>5- Publish and Find It</h3><p>Same publish step as Part 3: press F5, or run <strong>AL: Publish</strong> from the command palette. The extension compiles, deploys to the container, and BC opens in your browser.</p><p>Once it loads:</p><p>1- Press Alt+Q to open Tell Me, or click the magnifying-glass icon in the top-right of the page. (This is not the same as Ctrl+F Find, which only searches within the current page.) 2- Type &quot;Project Task&quot;. The list page appears because of UsageCategory = Lists.</p><p>2- Type “Project Task”. The list page appears because of UsageCategory = Lists.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X13EwHBHXfiuSnDh9B7WyA.png" /></figure><p>3- Open it, hit <strong>New</strong>, and create a couple of tasks. Give them a number, a description, and a due date. Leave the status on Open.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9rE_Kcam7vVmNON_Ig82TQ.png" /></figure><p>4- Open one task to its card and click <strong>Complete Task</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vM9pq9AUWC15xQjkmZJmbw.png" /></figure><p>The status flips to Completed and Completed On fills with today&#39;s date, read-only, exactly as the table and codeunit set it up. That&#39;s your own object, with your own logic, running in Business Central.</p><h3>What’s Next</h3><p>In Part 5 I’ll stop building separate objects and start modifying Microsoft’s. We’ll add a field to the Customer table with a tableextension, surface it on the Customer Card with a pageextension, and get into events and subscribers, the pattern that makes AL extensions actually production-grade.</p><p>If anything didn’t compile, check that your object IDs are in the 50000–99999 range and that the enum file exists before the table tries to reference it. Drop a comment if you hit something and I&#39;ll take a look.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4e1bfe3823f9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building an Invoice Automation Pipeline in C# with the Iron Suite]]></title>
            <link>https://albertassaad.medium.com/building-an-invoice-automation-pipeline-in-c-with-the-iron-suite-0572d62e4925?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/0572d62e4925</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[dotnet]]></category>
            <category><![CDATA[invoice-automation]]></category>
            <category><![CDATA[csharp]]></category>
            <category><![CDATA[automation]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Mon, 29 Jun 2026 10:22:17 GMT</pubDate>
            <atom:updated>2026-06-29T10:22:17.375Z</atom:updated>
            <content:encoded><![CDATA[<p>Read a spreadsheet, generate styled PDF invoices, put a “Pay Now” QR code on each one, and bundle the whole month into a single ZIP. End to end, in one small .NET 8 console app.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ROQDiBimXqELjSTFkC-UFw.png" /></figure><p>Have you ever watched someone build invoices by hand?</p><p>It usually goes like this. They open a spreadsheet of orders. They copy a customer name into a Word template, then a line item, then a price. They work out the tax on a calculator. They export to PDF, rename the file, drop it in a folder, and start the next one. Forty times. At the end of the month they zip everything up and email it to accounting.</p><p>It is slow and dull, and it is exactly the kind of repetitive work that puts a typo in the one invoice your biggest customer actually reads.</p><p>So let’s replace it with code. In this article we’ll build a small but complete invoice pipeline in C#. It takes a spreadsheet of orders and produces a folder of payment-ready PDF invoices, each with a scannable “Pay Now” QR code, plus one monthly ZIP archive. Each stage runs on a library from the Iron Suite, which is why the whole thing fits in a single .NET 8 console project without much plumbing.</p><p>I’ve written this for intermediate C# developers. You don’t need to know any of the Iron libraries beforehand. We’ll meet each one when we get to its stage.</p><h3>What we’re going to build</h3><p>The pipeline has four stages, and each maps to one Iron library:</p><pre>Invoices.xlsx  --IronXL--&gt;  Order rows (typed objects)<br>      |<br>      v<br>HTML template  --IronPDF--&gt;  A styled PDF per order<br>      |<br>      |-------IronQR-------&gt; A &quot;Pay Now&quot; QR embedded in each PDF<br>      v<br>output/invoices/*.pdf  --IronZIP--&gt;  output/Invoices-YYYY-MM.zip</pre><p>In plain English:</p><ol><li>Read the order and customer rows from an Excel file with IronXL.</li><li>Render a styled HTML invoice template into a PDF for each order with IronPDF.</li><li>Generate a “Pay Now” QR code for every invoice with IronQR.</li><li>Bundle the finished PDFs into one monthly archive with IronZIP.</li></ol><p>What I like about this shape is that the stages don’t know about each other. You could swap the spreadsheet for a database query, or replace the ZIP step with an email send, and the other three stages wouldn’t change.</p><p>The full project solution, source, sample spreadsheet, and HTML template is on GitHub if you’d rather clone and run it: <a href="https://github.com/AlbertAssaad/Invoice-Automation">https://github.com/AlbertAssaad/Invoice-Automation</a></p><h3>Prerequisites and NuGet setup</h3><p>You’ll need Visual Studio 2022 (17.8 or newer) or the .NET 8 SDK, and you’ll target .NET 8.0.</p><p>Create a new Console App named Invoice Automation, then add the four Iron packages. From the Package Manager Console:</p><pre>Install-Package IronXL.Excel<br>Install-Package IronPdf<br>Install-Package IronQR<br>Install-Package IronZIP</pre><p>Or with the dotnet CLI:</p><pre>dotnet add package IronXL.Excel<br>dotnet add package IronPdf<br>dotnet add package IronQR<br>dotnet add package IronZIP</pre><p>We’ll also read the license key and a couple of file paths from appsettings.json, so add the configuration packages too:</p><pre>dotnet add package Microsoft.Extensions.Configuration<br>dotnet add package Microsoft.Extensions.Configuration.Json</pre><p>When you’re done, the package references in your .csproj should look like this:</p><pre>&lt;ItemGroup&gt;<br>  &lt;!-- Four of the ten Iron Suite libraries; one Suite key covers them all. --&gt;<br>  &lt;PackageReference Include=&quot;IronXL.Excel&quot; Version=&quot;2026.5.1&quot; /&gt;   &lt;!-- Stage 1: read Excel --&gt;<br>  &lt;PackageReference Include=&quot;IronPdf&quot; Version=&quot;2026.6.1&quot; /&gt;        &lt;!-- Stage 2: HTML -&gt; PDF --&gt;<br>  &lt;PackageReference Include=&quot;IronQR&quot; Version=&quot;2026.4.1&quot; /&gt;         &lt;!-- Stage 3: QR codes   --&gt;<br>  &lt;PackageReference Include=&quot;IronZIP&quot; Version=&quot;2026.4.4&quot; /&gt;        &lt;!-- Stage 4: zip bundle  --&gt;<br><br>  &lt;PackageReference Include=&quot;Microsoft.Extensions.Configuration&quot; Version=&quot;8.0.0&quot; /&gt;<br>  &lt;PackageReference Include=&quot;Microsoft.Extensions.Configuration.Json&quot; Version=&quot;8.0.1&quot; /&gt;<br>&lt;/ItemGroup&gt;</pre><p>One small bit of housekeeping while you’re still in the .csproj. Three runtime assets (the appsettings.json file, the HTML template, and the sample spreadsheet) have to sit next to the compiled binary, or the app won&#39;t find them when it runs. Add a second &lt;ItemGroup&gt; that copies them on every build:</p><pre>&lt;ItemGroup&gt;<br>  &lt;None Update=&quot;appsettings.json&quot;&gt;<br>    &lt;CopyToOutputDirectory&gt;PreserveNewest&lt;/CopyToOutputDirectory&gt;<br>  &lt;/None&gt;<br>  &lt;None Update=&quot;Templates\InvoiceTemplate.html&quot;&gt;<br>    &lt;CopyToOutputDirectory&gt;PreserveNewest&lt;/CopyToOutputDirectory&gt;<br>  &lt;/None&gt;<br>  &lt;None Update=&quot;Data\Invoices.xlsx&quot;&gt;<br>    &lt;CopyToOutputDirectory&gt;PreserveNewest&lt;/CopyToOutputDirectory&gt;<br>  &lt;/None&gt;<br>&lt;/ItemGroup&gt;</pre><p>Skip this and you’ll lose five minutes wondering why a file that’s clearly right there can’t be found. PreserveNewest recopies a file only when it actually changes, so your builds stay quick.</p><h3>A word about licensing before we write any code</h3><p>This trips people up, so let’s settle it now. Every Iron library runs free in development. You can build and run this whole project without a key. Generated files may carry a trial watermark until you apply one, and you’ll want a real license for production, but nothing stops you from following along today.</p><p>When you go live, a single Iron Suite key turns on all four libraries at once. I like to keep that in one tiny class so it runs before any library is touched:</p><pre>namespace InvoiceAutomation.Licensing;<br><br>/// &lt;summary&gt;<br>/// Sets one Iron Suite key on each Iron library the app touches. The Suite key<br>/// covers all 10 products, but we only need these four.<br>/// &lt;/summary&gt;<br>public static class IronSuiteLicense<br>{<br>    public static void Apply(string licenseKey)<br>    {<br>        if (string.IsNullOrWhiteSpace(licenseKey))<br>            return; // Nothing to set; trial mode it is.<br><br>        // One key, four assignments. Do this before calling into any library.<br>        IronXL.License.LicenseKey  = licenseKey;<br>        IronPdf.License.LicenseKey = licenseKey;<br>        IronQr.License.LicenseKey  = licenseKey;<br>        IronZip.License.LicenseKey = licenseKey;<br>    }<br>}</pre><p>And the matching appsettings.json:</p><pre>{<br>  &quot;IronSuite&quot;: {<br>    &quot;LicenseKey&quot;: &quot;&quot;<br>  },<br>  &quot;Paths&quot;: {<br>    &quot;ExcelInput&quot;: &quot;Data/Invoices.xlsx&quot;,<br>    &quot;Output&quot;: &quot;output&quot;<br>  },<br>  &quot;Invoice&quot;: {<br>    &quot;CompanyName&quot;: &quot;Iron Forge Supply Co.&quot;,<br>    &quot;PayBaseUrl&quot;: &quot;https://pay.example.com/checkout&quot;<br>  }<br>}</pre><p>Leave LicenseKey blank to run in trial mode, and paste a key when you have one. (Iron Software hands out a free 30-day trial key on their site.)</p><h3>The data model</h3><p>Before the stages, we need something to carry data between them. Each spreadsheet row becomes one Order. Notice that subtotal, tax, and total are computed properties. We do the arithmetic once, in one place, so no later stage can get it wrong:</p><pre>namespace InvoiceAutomation.Models;<br><br>public sealed class Order<br>{<br>    public required string InvoiceNumber { get; init; }<br>    public DateTime OrderDate { get; init; }<br>    public required string CustomerName { get; init; }<br>    public required string CustomerEmail { get; init; }<br>    public required string BillingAddress { get; init; }<br>    public required string Item { get; init; }<br>    public int Quantity { get; init; }<br>    public decimal UnitPrice { get; init; }<br><br>    /// &lt;summary&gt;Tax rate stored as a fraction, so 0.08 means 8%.&lt;/summary&gt;<br>    public decimal TaxRate { get; init; }<br><br>    public decimal Subtotal =&gt; Quantity * UnitPrice;<br>    public decimal Tax =&gt; decimal.Round(Subtotal * TaxRate, 2, MidpointRounding.AwayFromZero);<br>    public decimal Total =&gt; Subtotal + Tax;<br>}</pre><p>The sample Invoices.xlsx has nine columns (InvoiceNumber, OrderDate, CustomerName, CustomerEmail, BillingAddress, Item, Quantity, UnitPrice, TaxRate) and five fake orders to play with.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*po3HE99awIfbI_N0lOxLBg.png" /></figure><p>Now to the four stages.</p><h3>Stage 1: reading orders from Excel with IronXL</h3><p>The first job is to get those rows out of the spreadsheet and into Order objects. This is where a lot of &quot;Excel in C#&quot; tutorials go wrong, because the old approach (COM Interop) needs Microsoft Office installed on the machine and crawls.</p><p>IronXL skips all of that. It reads .xlsx, .xls, and .csv files directly, with no Office and no Interop, so the same code runs on your laptop, on a Linux box, and in a CI container.</p><p>There are three steps. Load the workbook with WorkBook.Load(path), grab a worksheet, then walk the rows reading each cell through a typed accessor like .StringValue, .IntValue, .DecimalValue, or .DateTimeValue.</p><p>Here’s the full reader:</p><pre>using InvoiceAutomation.Models;<br>using IronXL;<br><br>namespace InvoiceAutomation.Pipeline;<br><br>/// &lt;summary&gt;<br>/// Stage 1: read the order rows out of the .xlsx with IronXL.<br>/// IronXL doesn&#39;t need Office or COM Interop installed, so this happily runs on<br>/// Windows, Linux, in containers, or on a CI box.<br>/// &lt;/summary&gt;<br>public sealed class ExcelOrderReader<br>{<br>    public IReadOnlyList&lt;Order&gt; ReadOrders(string excelPath)<br>    {<br>        if (!File.Exists(excelPath))<br>            throw new FileNotFoundException($&quot;Spreadsheet not found: {excelPath}&quot;);<br><br>        // Open the workbook, take the first sheet.<br>        WorkBook workBook = WorkBook.Load(excelPath);<br>        WorkSheet sheet = workBook.WorkSheets.First();<br><br>        var orders = new List&lt;Order&gt;();<br><br>        // Headers live in row 1, so the data starts at row 2. Rather than ask<br>        // IronXL for the used range, I just read down until the invoice-number<br>        // cell comes back empty.<br>        for (int row = 2; ; row++)<br>        {<br>            string invoiceNumber = sheet[$&quot;A{row}&quot;].StringValue;<br>            if (string.IsNullOrWhiteSpace(invoiceNumber))<br>                break;<br><br>            // The typed accessors (.StringValue, .IntValue, .DecimalValue,<br>            // .DateTimeValue) save you from parsing cells by hand.<br>            orders.Add(new Order<br>            {<br>                InvoiceNumber  = invoiceNumber.Trim(),<br>                // DateTimeValue is nullable, so fall back to today if the cell isn&#39;t a date.<br>                OrderDate      = sheet[$&quot;B{row}&quot;].DateTimeValue ?? DateTime.Today,<br>                CustomerName   = sheet[$&quot;C{row}&quot;].StringValue.Trim(),<br>                CustomerEmail  = sheet[$&quot;D{row}&quot;].StringValue.Trim(),<br>                BillingAddress = sheet[$&quot;E{row}&quot;].StringValue.Trim(),<br>                Item           = sheet[$&quot;F{row}&quot;].StringValue.Trim(),<br>                Quantity       = sheet[$&quot;G{row}&quot;].IntValue,<br>                UnitPrice      = sheet[$&quot;H{row}&quot;].DecimalValue,<br>                TaxRate        = sheet[$&quot;I{row}&quot;].DecimalValue,<br>            });<br>        }<br><br>        return orders;<br>    }<br>}</pre><p>Two details are worth your attention. First, sheet[$&quot;A{row}&quot;] uses ordinary Excel cell references (&quot;A2&quot;, &quot;B2&quot;, and so on), so the mapping from spreadsheet to object stays easy to read. Second, DateTimeValue returns DateTime?, not DateTime, so I use ?? DateTime.Today as a fallback when a cell isn&#39;t a real date.</p><p>After this stage, we have a clean List&lt;Order&gt; and the spreadsheet is out of the picture.</p><h3>Stage 2: rendering a PDF invoice with IronPDF</h3><p>Now the part I actually enjoy: turning each order into a good-looking PDF.</p><p>The trick that makes this pleasant is to design the invoice in HTML and CSS instead of positioning text and boxes by hand. You already know HTML, it’s easy to restyle, and you can preview it in a browser before you ever run the app. IronPDF then renders that HTML to PDF with a real Chromium engine, so what you see in Chrome is what lands in the file: web fonts, flexbox, background colors, all of it.</p><h3>The template</h3><p>The template is a normal HTML file with {{TOKENS}} where the data goes. Here&#39;s a trimmed slice so you can see the shape. The full file styles a header, a bill-to block, a line-items table, totals, and the payment panel:</p><pre>&lt;div class=&quot;header&quot;&gt;<br>  &lt;div class=&quot;brand&quot;&gt;▰ {{COMPANY_NAME}}&lt;/div&gt;<br>  &lt;div class=&quot;doc-title&quot;&gt;<br>    &lt;h1&gt;INVOICE&lt;/h1&gt;<br>    &lt;div class=&quot;doc-meta&quot;&gt;<br>      &lt;div&gt;&lt;strong&gt;{{INVOICE_NUMBER}}&lt;/strong&gt;&lt;/div&gt;<br>      &lt;div&gt;Issued {{ORDER_DATE}}&lt;/div&gt;<br>    &lt;/div&gt;<br>  &lt;/div&gt;<br>&lt;/div&gt;<br><br>&lt;!-- ... bill-to + line items ... --&gt;<br><br>&lt;div class=&quot;pay&quot;&gt;<br>  &lt;img src=&quot;{{QR_DATA_URI}}&quot; alt=&quot;Scan to pay invoice {{INVOICE_NUMBER}}&quot; /&gt;<br>  &lt;div class=&quot;pay-copy&quot;&gt;<br>    &lt;h3&gt;Pay now — scan to settle this invoice&lt;/h3&gt;<br>    &lt;p class=&quot;url&quot;&gt;{{PAY_URL}}&lt;/p&gt;<br>  &lt;/div&gt;<br>&lt;/div&gt;</pre><p>See {{QR_DATA_URI}} sitting inside an ordinary &lt;img&gt; tag? That&#39;s where the QR code from Stage 3 ends up, embedded as a base64 data URI rather than a separate file. The upside is that the PDF carries its own image and there are no temp files to clean up.</p><h3>The renderer</h3><p>The renderer does three things: it configures a ChromePdfRenderer once, fills the template tokens for a given order, and renders to PDF asynchronously.</p><pre>using InvoiceAutomation.Models;<br>using InvoiceAutomation.Util;<br>using IronPdf;<br>using System.Globalization;<br><br>namespace InvoiceAutomation.Pipeline;<br><br>/// &lt;summary&gt;<br>/// Stage 2: take one styled HTML invoice and render it to a PDF through<br>/// IronPDF&#39;s Chromium engine, with the IronQR &quot;pay now&quot; code sitting inline.<br>/// &lt;/summary&gt;<br>public sealed class InvoicePdfRenderer<br>{<br>    private readonly string _templateHtml;<br>    private readonly string _companyName;<br>    private readonly ChromePdfRenderer _renderer;<br><br>    public InvoicePdfRenderer(string templateHtml, string companyName)<br>    {<br>        _templateHtml = templateHtml;<br>        _companyName  = companyName;<br><br>        // Build the renderer once and reuse it for every invoice.<br>        _renderer = new ChromePdfRenderer();<br>        _renderer.RenderingOptions.PrintHtmlBackgrounds = true;                 // otherwise CSS backgrounds drop out<br>        _renderer.RenderingOptions.PaperSize    = IronPdf.Rendering.PdfPaperSize.A4;<br>        _renderer.RenderingOptions.MarginTop    = 12; // mm<br>        _renderer.RenderingOptions.MarginBottom = 12;<br>        _renderer.RenderingOptions.MarginLeft   = 12;<br>        _renderer.RenderingOptions.MarginRight  = 12;<br>    }<br><br>    public async Task&lt;string&gt; RenderAsync(Order order, byte[] qrPng, string payUrl, string outputDirectory)<br>    {<br>        string qrDataUri = &quot;data:image/png;base64,&quot; + Convert.ToBase64String(qrPng);<br>        string html = BuildHtml(order, qrDataUri, payUrl);<br><br>        // Chromium does the rendering, so the PDF matches the HTML and CSS exactly.<br>        PdfDocument pdf = await _renderer.RenderHtmlAsPdfAsync(html);<br><br>        Directory.CreateDirectory(outputDirectory);<br>        string pdfPath = Path.Combine(outputDirectory, $&quot;{order.InvoiceNumber}.pdf&quot;);<br>        pdf.SaveAs(pdfPath);<br>        return pdfPath;<br>    }<br><br>    private string BuildHtml(Order order, string qrDataUri, string payUrl) =&gt;<br>        _templateHtml<br>            .Replace(&quot;{{COMPANY_NAME}}&quot;,    _companyName)<br>            .Replace(&quot;{{INVOICE_NUMBER}}&quot;,  order.InvoiceNumber)<br>            .Replace(&quot;{{ORDER_DATE}}&quot;,      order.OrderDate.ToString(&quot;MMMM d, yyyy&quot;, CultureInfo.InvariantCulture))<br>            .Replace(&quot;{{CUSTOMER_NAME}}&quot;,   order.CustomerName)<br>            .Replace(&quot;{{CUSTOMER_EMAIL}}&quot;,  order.CustomerEmail)<br>            .Replace(&quot;{{BILLING_ADDRESS}}&quot;, order.BillingAddress)<br>            .Replace(&quot;{{ITEM}}&quot;,            order.Item)<br>            .Replace(&quot;{{QUANTITY}}&quot;,        order.Quantity.ToString(CultureInfo.InvariantCulture))<br>            .Replace(&quot;{{UNIT_PRICE}}&quot;,      Formatting.Money(order.UnitPrice))<br>            .Replace(&quot;{{SUBTOTAL}}&quot;,        Formatting.Money(order.Subtotal))<br>            .Replace(&quot;{{TAX_RATE}}&quot;,        (order.TaxRate * 100m).ToString(&quot;0.##&quot;, CultureInfo.InvariantCulture) + &quot;%&quot;)<br>            .Replace(&quot;{{TAX}}&quot;,             Formatting.Money(order.Tax))<br>            .Replace(&quot;{{TOTAL}}&quot;,           Formatting.Money(order.Total))<br>            .Replace(&quot;{{QR_DATA_URI}}&quot;,     qrDataUri)<br>            .Replace(&quot;{{PAY_URL}}&quot;,         payUrl)<br>            .Replace(&quot;{{GENERATED_ON}}&quot;,    DateTime.Now.ToString(&quot;yyyy-MM-dd HH:mm&quot;, CultureInfo.InvariantCulture));<br>}</pre><p>Three choices here make the difference in real use:</p><ol><li>The renderer is created once. Starting Chromium has a cost, so we build a single ChromePdfRenderer in the constructor and reuse it for every order instead of spinning one up per invoice.</li><li>PrintHtmlBackgrounds = true. Print styling drops background colors by default, which would flatten the dark header band and the tinted payment panel. This keeps them.</li><li>RenderHtmlAsPdfAsync. Rendering is genuinely async, so when you scale to hundreds of invoices you aren&#39;t blocking a thread per document.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oJabDkTpVTo8zhkeNuoX4A.png" /></figure><h3>Stage 3: stamping a “Pay Now” QR code with IronQR</h3><p>A modern invoice should let the customer pay in seconds. So we’ll encode a payment URL as a QR code they can scan with a phone camera to land straight on a checkout page.</p><p>For that we use IronQR, Iron Software’s dedicated QR library. If you’re curious about what’s actually happening inside those black-and-white squares, the position patterns and error correction and encoding modes, I wrote a separate piece on <a href="https://medium.com/analytics-vidhya/whats-inside-the-qr-code-bf8a465378fd">what’s inside a QR code</a>.</p><p>Generating one is about as short as it gets:</p><pre>using IronQr;<br>using IronSoftware.Drawing; // AnyBitmap<br><br>namespace InvoiceAutomation.Pipeline;<br><br>/// &lt;summary&gt;<br>/// Stage 3: encode the &quot;pay now&quot; payload (a payment URL in this case) to PNG<br>/// bytes with IronQR. Handing back raw bytes means the renderer can drop the QR<br>/// into the invoice HTML as a data URI, and we never write a temp file.<br>/// &lt;/summary&gt;<br>public sealed class QrCodeGenerator<br>{<br>    public byte[] GeneratePngBytes(string payload)<br>    {<br>        // Medium correction trades a little density for better scan reliability.<br>        var options = new QrOptions(QrErrorCorrectionLevel.Medium);<br>        QrCode qr = QrWriter.Write(payload, options);<br><br>        // Draw it into memory and export the PNG bytes.<br>        AnyBitmap bitmap = qr.Save();<br><br>        using var stream = new MemoryStream();<br>        bitmap.ExportStream(stream, AnyBitmap.ImageFormat.Png, 100);<br>        return stream.ToArray();<br>    }<br>}</pre><p>Walking through it: QrOptions(QrErrorCorrectionLevel.Medium) sets the error-correction level. Higher levels survive more damage, a coffee ring or a fold, at the cost of a denser code, and Medium is a sensible middle for a clean printed invoice. QrWriter.Write(payload, options) produces the QrCode. Then qr.Save() gives an AnyBitmap, Iron Software&#39;s cross-platform image type, and ExportStream writes PNG bytes into a MemoryStream.</p><p>Returning a byte[] is deliberate. Back in Stage 2 the renderer turns those bytes into a data:image/png;base64,... URI and drops them into the &lt;img&gt; tag, so the QR rides inside the PDF with no file juggling.</p><p>What goes in the QR ? A payment link built per order. In the orchestrator we’ll assemble something like:</p><pre>https://pay.example.com/checkout?invoice=INV-1002&amp;amount=2489.75</pre><p>In production you’d point PayBaseUrl at your real gateway, a Stripe Checkout link or a PayPal button or your billing portal, and the customer is one scan from paying.</p><h3>Stage 4: bundling the month with IronZIP</h3><p>At month-end you rarely want forty loose PDFs. You want one file to archive or hand to accounting. IronZIP turns the folder of invoices into a single compressed archive.</p><pre>using IronZip;<br><br>namespace InvoiceAutomation.Pipeline;<br><br>/// &lt;summary&gt;<br>/// Stage 4: pack the month&#39;s PDFs into one .zip with IronZIP.<br>/// &lt;/summary&gt;<br>public sealed class ArchiveBuilder<br>{<br>    public string CreateMonthlyArchive(IEnumerable&lt;string&gt; pdfPaths, string outputDirectory, string archiveName)<br>    {<br>        Directory.CreateDirectory(outputDirectory);<br>        string zipPath = Path.Combine(outputDirectory, archiveName);<br><br>        // Fresh archive. Compression defaults to level 9, the maximum.<br>        using var archive = new IronZipArchive();<br><br>        foreach (string pdf in pdfPaths)<br>            archive.Add(pdf); // one entry per PDF<br><br>        archive.SaveAs(zipPath);<br>        return zipPath;<br>    }<br>}</pre><p>The pattern is hard to misuse. new IronZipArchive() opens a fresh archive; the constructor takes an optional compression level from 0 (store) to 9 (maximum), and 9 is the default. archive.Add(path) adds a file, and each entry shows up as a flat file when the archive is extracted. archive.SaveAs(path) writes the .zip to disk, and wrapping the whole thing in a using block disposes it cleanly afterward.</p><h3>Wiring the four stages together</h3><p>Each stage is a small, focused class. The orchestrator is the part that reads like the story of the pipeline:</p><pre>public async Task RunAsync()<br>{<br>    // Paths in config are relative to the binary, which is where the .csproj<br>    // drops the assets, so resolve them against the app base directory.<br>    string excelPath    = Resolve(_config.ExcelInputPath);<br>    string outputRoot   = Resolve(_config.OutputDirectory);<br>    string invoicesDir  = Path.Combine(outputRoot, &quot;invoices&quot;);<br>    string templatePath = Resolve(Path.Combine(&quot;Templates&quot;, &quot;InvoiceTemplate.html&quot;));<br><br>    // Stage 1: pull the orders out of Excel.<br>    IReadOnlyList&lt;Order&gt; orders = _reader.ReadOrders(excelPath);<br>    Console.WriteLine($&quot;[1/4] IronXL   - read {orders.Count} order(s) from {Path.GetFileName(excelPath)}&quot;);<br><br>    string templateHtml = await File.ReadAllTextAsync(templatePath);<br>    var renderer = new InvoicePdfRenderer(templateHtml, _config.CompanyName);<br><br>    // Stages 2 and 3: one PDF per order, each carrying its own QR code.<br>    var pdfPaths = new List&lt;string&gt;();<br>    foreach (Order order in orders)<br>    {<br>        // The QR points at a payment link. Swap PayBaseUrl for your real<br>        // gateway (Stripe Checkout, PayPal, whatever you use) in production.<br>        string payUrl = $&quot;{_config.PayBaseUrl}&quot; +<br>                        $&quot;?invoice={Uri.EscapeDataString(order.InvoiceNumber)}&quot; +<br>                        $&quot;&amp;amount={order.Total.ToString(CultureInfo.InvariantCulture)}&quot;;<br><br>        byte[] qrPng   = _qr.GeneratePngBytes(payUrl);                              // IronQR<br>        string pdfPath = await renderer.RenderAsync(order, qrPng, payUrl, invoicesDir); // IronPDF<br>        pdfPaths.Add(pdfPath);<br><br>        Console.WriteLine($&quot;[2/4] IronPDF  - {Path.GetFileName(pdfPath),-16} {order.CustomerName} ({Formatting.Money(order.Total)})&quot;);<br>    }<br><br>    // Stage 4: roll the whole month into a single zip.<br>    string archiveName = $&quot;Invoices-{DateTime.Now:yyyy-MM}.zip&quot;;<br>    string zipPath = new ArchiveBuilder().CreateMonthlyArchive(pdfPaths, outputRoot, archiveName);<br>    Console.WriteLine($&quot;[4/4] IronZIP   - bundled {pdfPaths.Count} PDF(s) into {Path.GetFileName(zipPath)}&quot;);<br>}</pre><p>And Program.cs ties configuration, licensing, and the pipeline together. Top-level statements keep it short enough to read in one go:</p><pre>using InvoiceAutomation.Configuration;<br>using InvoiceAutomation.Licensing;<br>using InvoiceAutomation.Pipeline;<br><br>Console.WriteLine(&quot;Invoice Automation Pipeline - powered by the Iron Suite&quot;);<br>Console.WriteLine(&quot;=======================================================&quot;);<br><br>// Pull the license key and file paths out of appsettings.json.<br>AppConfig config = AppConfig.Load();<br><br>// The same Iron Suite key activates all four libraries. If you leave it blank<br>// the app still runs, just in trial mode.<br>IronSuiteLicense.Apply(config.LicenseKey);<br>if (string.IsNullOrWhiteSpace(config.LicenseKey))<br>    Console.WriteLine(&quot;(No license key set, running Iron Suite in TRIAL mode; dev use only.)\n&quot;);<br><br>// Off we go.<br>try<br>{<br>    await new InvoicePipeline(config).RunAsync();<br>}<br>catch (Exception ex)<br>{<br>    Console.Error.WriteLine($&quot;\nPipeline failed: {ex.Message}&quot;);<br>    Environment.ExitCode = 1;<br>}</pre><h3>Running it</h3><p>Press F5 in Visual Studio, or run dotnet run from the project folder. Each stage reports as it goes:</p><pre>Invoice Automation Pipeline — powered by the Iron Suite<br>=======================================================<br>(No license key set — running Iron Suite in TRIAL mode; dev use only.)<br><br>[1/4] IronXL   — read 5 order(s) from Invoices.xlsx<br>[2/4] IronPDF  — INV-1001.pdf     Acme Robotics ($809.97)<br>[2/4] IronPDF  — INV-1002.pdf     Globex Corporation ($2,489.75)<br>[2/4] IronPDF  — INV-1003.pdf     Initech LLC ($844.69)<br>[2/4] IronPDF  — INV-1004.pdf     Umbrella Health ($1,113.00)<br>[2/4] IronPDF  — INV-1005.pdf     Wayne Enterprises ($2,745.62)<br>[4/4] IronZIP   — bundled 5 PDF(s) into Invoices-2026-06.zip<br><br>Done. Output folder: ...\bin\Debug\net8.0\output</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9lZRe34nOF1EVee16_1wNA.png" /></figure><p>Two things to expect on that first run. One: there’s no [3/4] IronQR line in the output, and that&#39;s on purpose. IronQR runs inside the Stage 2 loop, building each QR code just before its invoice is rendered, so it does its job without printing a status line of its own. All four libraries are working; three of them just happen to announce themselves.</p><p>Two: the very first run is the slow one. The first time IronPDF renders anything, it downloads and unpacks its Chromium engine, so give it a few seconds and a live network connection. That engine is then cached on the machine, and every run after that skips the download. Once it’s warm, a batch this size finishes in about a second.</p><p>Look in bin/Debug/net8.0/output/ and you&#39;ll find:</p><pre>output/<br>├── invoices/<br>│   ├── INV-1001.pdf<br>│   ├── INV-1002.pdf<br>│   ├── INV-1003.pdf<br>│   ├── INV-1004.pdf<br>│   └── INV-1005.pdf<br>└── Invoices-2026-06.zip</pre><p>Five styled invoices, each with a working “Pay Now” QR code, bundled into one archive, all built from a single spreadsheet in about a second once the engine is warm. The month-end ritual we opened with is now a single keystroke.</p><h3>Why the Iron Suite fits here</h3><p>Look back at what we never had to do. We didn’t install Microsoft Office to read Excel. We didn’t hand-position text in a low-level PDF drawing API. We didn’t bolt on a separate QR package with its own conventions or a third-party zip wrapper with another. Four stages, four libraries, one consistent style of API, and they’re built to hand off to each other (that AnyBitmap from IronQR drops straight into the IronPDF render, for instance).</p><p>The licensing is where it adds up. A single Iron Suite key switches on all ten libraries at once, the same key we set in IronSuiteLicense.Apply at the very start of the app. So if you later pull in IronWord to draft a contract, or IronOCR to read a scanned receipt back into the pipeline, there&#39;s nothing new to wire up. The code in this project already activated them. When you&#39;re ready for production, you can always ask Iron Software for a license; just reach out through their website.</p><h3>Wrap-up and next steps</h3><p>Quick recap. We took a spreadsheet of orders and ran it through four stages. IronXL read the rows into typed Order objects, IronPDF rendered an HTML template into a styled PDF per order, IronQR generated the scannable &quot;Pay Now&quot; code embedded in each invoice, and IronZIP bundled the month into one archive.</p><p>Because the stages are independent, this is a good base to build on. A few directions I’d take it next:</p><ul><li>Email delivery: send each PDF to its customer automatically. The CustomerEmail field is already sitting there.</li><li>A real database: swap ExcelOrderReader for a query against your orders table and nothing else changes.</li><li>Multiple line items: extend Order to hold a list of items and loop over them in the template&#39;s table.</li><li>Digital signatures: IronPDF can cryptographically sign each invoice before it goes out.</li><li>Run it on a schedule: drop the console app on a server and fire it on the first of every month.</li></ul><p>The full project (solution, source, sample spreadsheet, HTML template, and a browser-viewable invoice preview) is on GitHub at <a href="https://github.com/AlbertAssaad/Invoice-Automation">https://github.com/AlbertAssaad/Invoice-Automation</a> — it opens in Visual Studio 2022 and runs as-is.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0572d62e4925" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a QR Code Generator Tool with WPF and MVVM and IronBarcode]]></title>
            <link>https://albertassaad.medium.com/building-a-qr-code-generator-tool-with-wpf-and-mvvm-and-ironbarcode-2d95f8ea008b?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/2d95f8ea008b</guid>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Fri, 22 May 2026 10:44:50 GMT</pubDate>
            <atom:updated>2026-05-22T10:44:50.108Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8Hw3dCkc5L5OK7OSBnEVRw.jpeg" /><figcaption>Generated by Chatgpt</figcaption></figure><p>As per our last <a href="https://medium.com/analytics-vidhya/whats-inside-the-qr-code-bf8a465378fd">article</a>, we went deep into the internals of QR codes :the finder patterns, the timing patterns, the masking XOR operations, all the way down to decoding binary modules by hand. Now that we understand what lives inside a QR code, let’s build something practical: a desktop app that generates them.</p><h3>The Project</h3><p>QRCodeToolbox is a WPF application built on .NET 10 that lets you type any text, generate a QR code instantly, preview it, copy it to the clipboard, or save it as a PNG file. It follows the MVVM pattern,clean separation between the UI, the view model, and the model that does the actual work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/886/1*zJhKSDU3z4cpAFyW24RYUA.png" /></figure><p>The project structure is straightforward:</p><pre>QRCodeToolbox/<br>├── Models/<br>│   └── QRCodeModel.cs        ← QR generation logic lives here<br>├── ViewModels/<br>│   ├── MainViewModel.cs      ← Commands and UI state<br>│   ├── ViewModelBase.cs      ← INotifyPropertyChanged base<br>│   └── RelayCommand.cs       ← ICommand implementation<br>└── MainWindow.xaml           ← The UI</pre><h3>The Library: IronBarcode</h3><p>For QR generation I reached for <a href="https://ironsoftware.com/csharp/barcode/">IronBarcode</a> by Iron Software. It is a .NET barcode and QR code library that handles the full stack :generating, styling, and reading barcodes with a clean, readable API.</p><p>You install it via NuGet:</p><pre>dotnet add package Barcode</pre><p>No native dependencies, no platform headaches. It just works.</p><h3>The Model</h3><p>The entire generation logic sits in QRCodeModel.cs. As we discussed in our last article, a QR code has error correction levels : Low, Medium, High, Highest,that trade capacity for resilience. Here we use Medium, which recovers from up to 15% damage:</p><pre>using IronBarCode;<br>using System.Drawing;<br>using System.Windows.Media.Imaging;<br>using System.IO;<br>namespace QRCodeToolbox.Models<br>{<br>public class QRCodeModel<br>{<br>    public string? Text { get; set; }<br>    public int PixelsPerModule { get; set; } = 70;<br>    public BitmapImage? GenerateQRCode()<br>    {<br>        if (string.IsNullOrWhiteSpace(Text))<br>            throw new ArgumentException(&quot;Text cannot be empty&quot;);<br>        GeneratedBarcode qrCode = QRCodeWriter.CreateQrCode(<br>            Text,<br>            PixelsPerModule,<br>            QRCodeWriter.QrErrorCorrectionLevel.Medium<br>        );<br>        Bitmap qrCodeImage = qrCode.ToBitmap();<br>        return BitmapToImageSource(qrCodeImage);<br>    }<br>     public void SaveQRCodeToFile(string filePath)<br>    {<br>        if (string.IsNullOrWhiteSpace(Text))<br>            throw new ArgumentException(&quot;Text cannot be empty&quot;);<br>        try<br>        {<br>            GeneratedBarcode qrCode = QRCodeWriter.CreateQrCode(Text, PixelsPerModule, QRCodeWriter.QrErrorCorrectionLevel.Medium);<br>            qrCode.SaveAsPng(filePath);                <br>        } <br>        catch (Exception ex)<br>        {<br>            throw new InvalidOperationException(&quot;Failed to save QR code&quot;, ex);<br>        }<br>    }<br>}<br>}</pre><p>The PixelsPerModule parameter maps directly to what we covered in the last article ,each dark or light square in the QR grid is a module. The higher this number, the larger and sharper the generated image. We default to 70 pixels per module, which gives a crisp result for most use cases.</p><p>One thing worth noting: IronBarcode returns a GeneratedBarcode object, not just a raw image. That object gives you .ToBitmap(), .SaveAsPng(), .SaveAsHtmlFile(), .ToStream(), and more. You choose the format at the last step, which keeps the generation logic clean.</p><h3>Displaying in WPF: The Bitmap Conversion</h3><p>WPF uses BitmapImage, not System.Drawing.Bitmap. So we need a conversion step. We also take the opportunity to scale the image up with nearest-neighbour interpolation this keeps the modules sharp-edged rather than blurry:</p><pre>private static BitmapImage BitmapToImageSource(Bitmap bitmap)<br>{<br>    int scaleFactor = 3;<br>    Bitmap scaledBitmap = new Bitmap(<br>        bitmap.Width * scaleFactor,<br>        bitmap.Height * scaleFactor<br>    );<br><br>    using (Graphics g = Graphics.FromImage(scaledBitmap))<br>    {<br>        g.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.NearestNeighbor;<br>        g.DrawImage(bitmap, 0, 0, scaledBitmap.Width, scaledBitmap.Height);<br>    }<br><br>    BitmapImage bitmapImage = new BitmapImage();<br>    bitmapImage.BeginInit();<br>    bitmapImage.CacheOption = BitmapCacheOption.OnLoad;<br><br>    using (MemoryStream memoryStream = new MemoryStream())<br>    {<br>        scaledBitmap.Save(memoryStream, System.Drawing.Imaging.ImageFormat.Png);<br>        memoryStream.Seek(0, SeekOrigin.Begin);<br>        bitmapImage.StreamSource = memoryStream;<br>        bitmapImage.EndInit();<br>        bitmapImage.Freeze();<br>    }<br><br>    bitmap.Dispose();<br>    scaledBitmap.Dispose();<br>    return bitmapImage;<br>}</pre><p>bitmapImage.Freeze() is important for WPF ,it makes the object immutable and thread-safe for binding.</p><h3>The ViewModel</h3><p>The MainViewModel wires everything together. It exposes four commands:</p><ul><li><strong>GenerateCommand</strong> : enabled when input text is not empty</li><li><strong>SaveCommand : </strong>enabled when a QR code has been generated</li><li><strong>CopyCommand</strong> : enabled when a QR code has been generated</li><li><strong>ClearCommand</strong> : always enabled</li></ul><pre>GenerateCommand = new RelayCommand(<br>    _ =&gt; GenerateQRCode(),<br>    _ =&gt; !string.IsNullOrWhiteSpace(InputText)<br>);<br><br>CopyCommand = new RelayCommand(<br>    _ =&gt; CopyToClipboard(),<br>    _ =&gt; QRCodeImage != null<br>);</pre><p>Copying to clipboard is a single line with WPF:</p><pre>Clipboard.SetImage(QRCodeImage);</pre><p>The view binds to QRCodeImage, InputText, StatusMessage, and PixelsPerModule entirely through data binding ,MainWindow.xaml.cs contains nothing but the DataContext assignment:</p><pre>public MainWindow()<br>{<br>    InitializeComponent();<br>    DataContext = new MainViewModel();<br>}</pre><h3>Why IronBarcode?</h3><p>When we manually decoded a QR code in our last article, we appreciated just how much is happening inside those black and white squares. Writing all of that from scratch encoding modes, error correction polynomials, module placement is weeks of work. IronBarcode packages all of it behind one method call:</p><pre>QRCodeWriter.CreateQrCode(text, pixelsPerModule, errorCorrectionLevel);</pre><p>It supports URL, text, email, and binary encoding out of the box, handles all four QR versions automatically based on data length, and the GeneratedBarcode result object gives you flexible output options (Bitmap, SVG, Stream, file). For .NET developers who need reliable barcode and QR functionality without reinventing the wheel, it is the cleanest option I have found.</p><p>You can explore the full documentation and licensing options at <a href="https://ironsoftware.com/csharp/barcode/">ironsoftware.com/csharp/barcode</a>.</p><p>The full source code for QRCodeToolbox is available on <a href="https://github.com/AlbertAssaad/QRCodeToolbox.git">GitHub</a>. If you missed it, go back and read <a href="https://medium.com/analytics-vidhya/whats-inside-the-qr-code-bf8a465378fd"><em>What’s Inside The QR Code</em></a><em>?</em> first.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2d95f8ea008b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Secure Remote Access to Your On-Premise Network: Best Solutions]]></title>
            <link>https://albertassaad.medium.com/secure-remote-access-to-your-on-premise-network-best-solutions-92b163d3d69d?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/92b163d3d69d</guid>
            <category><![CDATA[networking]]></category>
            <category><![CDATA[self-hosted]]></category>
            <category><![CDATA[vpn]]></category>
            <category><![CDATA[cybersecurity]]></category>
            <category><![CDATA[network-security]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Tue, 12 May 2026 10:11:59 GMT</pubDate>
            <atom:updated>2026-05-12T10:11:59.157Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v8lkm2tofuwBgQsLeJuziw.png" /></figure><h3>1. The Problem Nobody Talks About</h3><p>The classic scenario: your company runs an on-premise network. Files live on a local NAS or file server. The ERP system (whether it’s Dynamics NAV, SAP Business One, or something else) is installed on a server in the back room. A developer needs to RDP into a workstation. A sales manager needs to pull a report from headquarters while working remotely.</p><p>The textbook answer in 2024 is usually “move everything to the cloud” or “deploy a SASE platform.” But for a huge segment of companies, particularly in regions with unreliable internet, businesses with strict data residency requirements, or firms that simply can’t justify the cost and complexity of platforms like Zscaler or Cisco Umbrella, that answer is simply not practical.</p><p>What you actually need is a secure, auditable, manageable tunnel from a remote device into your local network, with proper authentication and without exposing your internal servers to the public internet.</p><p>This article walks you through exactly that: the architecture, the best tools available today, and how to pick the right combination for your specific situation.</p><h3>2. The Core Concepts You Need to Understand</h3><p>Before picking a solution, it helps to align on a few key terms, not as dry definitions, but as things that will directly influence your architecture choices.</p><p><strong>VPN (Virtual Private Network)</strong> is the broad category. A VPN creates an encrypted tunnel between two endpoints, typically a remote user’s device and a gateway on your local network. Traffic flows through this tunnel as if the remote device were physically plugged into the office switch.</p><p><strong>Tunneling protocol</strong> is what VPN runs on top of. OpenVPN uses TLS/SSL. WireGuard uses modern cryptography (ChaCha20, Curve25519). IPSec is common in enterprise hardware. The protocol determines performance, security, and compatibility.</p><p><strong>CGNAT (Carrier-Grade NAT)</strong> is a real headache for on-premise deployments. Many ISPs, especially in developing markets and for residential connections, assign multiple customers to a single public IP. This means your office network may sit behind a NAT layer you don’t control, making it impossible to accept inbound connections. Some solutions handle this gracefully; others don’t.</p><p><strong>Zero Trust</strong> is a security model where no device or user is automatically trusted, regardless of whether they are inside the corporate network or outside it. Every connection is verified individually, and access is granted only to specific resources rather than to the entire network. In practice, a full Zero Trust implementation covers several layers: certificate or token-based authentication instead of passwords, device posture validation (checking that the connecting device meets security standards before granting access), continuous authorization (re-verifying identity during a session, not just at login), application-level segmentation (users reach only the apps they are permitted to use, not the whole network), and least-privilege enforcement (minimum access by default). It is worth being honest here: raw WireGuard handles authentication well but does not address posture validation, continuous authorization, or application segmentation on its own. Cloudflare Access partially implements Zero Trust at the application layer. A full Zero Trust deployment usually involves layering multiple tools. This article focuses on the secure tunneling foundation, which is the first and most critical step.</p><p><strong>Endpoint authentication</strong> means verifying not just <em>who</em> is connecting (the user) but <em>what</em> is connecting (the device). A strong setup rejects connections from unknown devices even if they have the correct credentials.</p><h3>3. How It Works Architecturally</h3><p>The fundamental flow in any remote access setup looks like this:</p><pre>[Remote Laptop] ──(encrypted tunnel)──&gt; [Gateway on your network] ──&gt; [Internal Resources]<br>    WireGuard / OpenVPN client              VPN server / Reverse proxy       File server, ERP, RDP...</pre><p>In a traditional VPN setup, the gateway (your office router or a dedicated server) listens on a public port. The remote device connects to that port, authenticates, and gets routed into the internal network.</p><p>In a <strong>reverse tunnel</strong> setup (used by Cloudflare Tunnel and Pangolin), the flow is inverted:</p><pre>[Internal server] ──(outbound connection)──&gt; [Relay server] &lt;── [Remote client connects here]<br>   Your office machine                          Cloud or VPS relay               Remote user</pre><p>Here, <em>your server initiates</em> the connection outward to a relay. No inbound ports need to be open on your firewall. This is particularly useful when your ISP uses CGNAT or when your firewall policies prohibit inbound connections.</p><p>The choice between these two architectures, direct VPN vs. reverse tunnel, is often dictated by your network conditions and your tolerance for complexity.</p><h3>4. The Best Solutions Available Today</h3><h3>4.1 WireGuard: The Modern VPN Foundation</h3><p><strong>What it is:</strong> WireGuard is an open-source VPN protocol, now built directly into the Linux kernel. It’s lean, fast, and cryptographically modern, a deliberate contrast to OpenVPN’s sprawling codebase.</p><p><strong>How it works:</strong> Each peer (server or client) has a public/private key pair. The server config lists allowed peers by their public key and assigns each a virtual IP. The client config points to the server’s endpoint and public key. Once both configs are in place, the tunnel comes up automatically.</p><p>A minimal server configuration looks like this:</p><pre>[Interface]<br>PrivateKey = &lt;server_private_key&gt;<br>Address = 10.0.0.1/24<br>ListenPort = 51820<br><br>[Peer]<br>PublicKey = &lt;client_public_key&gt;<br>AllowedIPs = 10.0.0.2/32</pre><p>And the corresponding client config:</p><pre>[Interface]<br>PrivateKey = &lt;client_private_key&gt;<br>Address = 10.0.0.2/24<br>DNS = 10.0.0.1<br><br>[Peer]<br>PublicKey = &lt;server_public_key&gt;<br>Endpoint = your.office.ip:51820<br>AllowedIPs = 192.168.1.0/24   # Route only office subnet through tunnel<br>PersistentKeepalive = 25</pre><p><strong>Best use case:</strong> Any company with a static public IP and the ability to forward a UDP port. Excellent for technical teams comfortable with CLI configuration.</p><p><strong>Pros:</strong> Extremely fast, minimal attack surface, kernel-level performance, no license costs.</p><p><strong>Cons:</strong> No built-in key management UI, no CGNAT support out of the box, requires manual peer configuration for each user.</p><p><strong>Cost:</strong> Free and open source.</p><h3>4.2 Tailscale: WireGuard Without the Headaches</h3><p><strong>What it is:</strong> Tailscale is a commercial overlay network product built on top of WireGuard. It handles the coordination layer, key exchange, peer discovery, and NAT traversal, that raw WireGuard leaves to you.</p><p><strong>How it works:</strong> Each device installs the Tailscale client, which registers with Tailscale’s coordination servers. Peers discover each other through these servers but communicate directly via WireGuard tunnels once connected. When direct connection isn’t possible (due to CGNAT), traffic is relayed through Tailscale’s DERP relay network.</p><p><strong>Best use case:</strong> Small teams who want WireGuard’s performance without manual configuration. Also excellent for CGNAT environments.</p><p><strong>Pros:</strong> Zero configuration, handles CGNAT natively, cross-platform, subnet routing lets remote users reach the entire office network.</p><p><strong>Cons:</strong> The coordination plane goes through Tailscale’s cloud (a concern for strict data residency requirements). Free tier is limited to 100 devices. Headscale (open source) can replace the coordination server for a fully self-hosted setup.</p><p><strong>Cost:</strong> Free up to 100 devices / 3 users. Team plan starts at ~$6/user/month.</p><h3>4.3 Cloudflare Tunnel: No Open Ports Required</h3><p><strong>What it is:</strong> Cloudflare Tunnel (formerly Argo Tunnel) lets you expose internal services to the internet, or to specific authenticated users, without opening any inbound ports on your firewall. Your server connects outbound to Cloudflare’s edge.</p><p><strong>How it works:</strong> You install the cloudflared daemon on an internal server. It establishes an outbound tunnel to Cloudflare. You configure which internal hostnames or ports map to which Cloudflare routes. Access can be gated behind Cloudflare Access (identity-aware proxy).</p><pre># Install and authenticate<br>cloudflared tunnel login<br>cloudflared tunnel create my-office-tunnel<br><br># Create a config pointing to an internal service<br>cloudflared tunnel route dns my-office-tunnel erp.company.com</pre><p><strong>Best use case:</strong> Exposing specific internal web applications (ERP web interface, internal dashboards, remote management portals) to authenticated remote users without a VPN.</p><p><strong>Cons:</strong> Traffic transits Cloudflare’s infrastructure, which is a trust decision you need to make consciously. Not ideal for full network-level access (for RDP, SMB, etc., you’d still want a VPN). Free tier bandwidth limits may apply.</p><blockquote><strong>Important:</strong> Never expose SMB or RDP directly to the internet, whether through Cloudflare Tunnel or any other method, without a VPN or identity-aware gateway in front of them. These protocols were not designed for internet-facing exposure and carry significant attack surface. Cloudflare Tunnel is appropriate for HTTP/HTTPS-based internal applications. For anything else, route it through a proper VPN first.</blockquote><p><strong>Cost:</strong> Cloudflare Tunnel itself is free. Cloudflare Access (for authentication) has a free tier for up to 50 users.</p><h3>4.4 Pangolin: Self-Hosted Tunneling</h3><p><strong>What it is:</strong> Pangolin is an open-source, self-hosted alternative to Cloudflare Tunnel. You run the relay server yourself on a VPS with a public IP, eliminating the dependency on any third-party cloud.</p><p><strong>How it works:</strong> You deploy the Pangolin server on a VPS (DigitalOcean, Hetzner, etc.). Your internal machine runs the Pangolin client, which connects outbound to your VPS relay. Incoming requests to your VPS are forwarded through the tunnel to the internal service.</p><p><strong>Best use case:</strong> Companies that want the CGNAT-bypassing benefits of a reverse tunnel but can’t route traffic through Cloudflare or any other third party.</p><p><strong>Pros:</strong> Fully self-hosted, no vendor dependency, CGNAT-safe, actively maintained.</p><p><strong>Cons:</strong> Requires a VPS to act as relay (adds a monthly server cost), more setup effort than Cloudflare Tunnel, smaller community. As with any newer open-source project, evaluate current maintenance activity and community health on GitHub before standardizing on Pangolin for production use. Established projects like Cloudflare and Tailscale carry significantly less abandonment risk.</p><p><strong>Cost:</strong> Free and open source. VPS relay adds ~$5–$10/month.</p><h3>4.5 OpenVPN: The Battle-Tested Classic</h3><p><strong>What it is:</strong> OpenVPN is the veteran of the VPN space. It’s been around since 2001, runs on everything, and is supported by virtually every firewall appliance on the market.</p><p><strong>How it works:</strong> OpenVPN uses TLS/SSL for authentication and key exchange, and UDP (or TCP) for the data tunnel. It supports both certificate-based and username/password authentication, and has a rich plugin ecosystem.</p><p><strong>Best use case:</strong> Environments where compatibility is the primary concern: legacy routers, strict firewall rules, or IT policies that require enterprise VPN support. Also good if you need to issue .ovpn config files to users who will import them into OpenVPN clients.</p><p><strong>Pros:</strong> Universally supported, extremely configurable, strong enterprise ecosystem, TCP mode works through restrictive firewalls that block UDP. OpenVPN also has mature support for LDAP, RADIUS, and SAML-based SSO integrations, and its TCP fallback mode is uniquely reliable in environments with aggressive deep-packet inspection. Many compliance frameworks (PCI-DSS, SOC 2) have auditors already familiar with OpenVPN, which can simplify certification. Some organizations deliberately choose OpenVPN not for raw performance but because operational tooling, audit familiarity, and integration depth matter more than throughput benchmarks.</p><p><strong>Cons:</strong> Slower than WireGuard, larger attack surface, more complex to configure and audit. OpenVPN Access Server (the official management UI) requires a commercial license beyond 2 simultaneous connections.</p><p><strong>Cost:</strong> OpenVPN Community Edition is free. Access Server is free for 2 connections, then $15/connection/year.</p><h3>4.6 pfSense / OPNsense: Full Gateway Control</h3><p><strong>What it is:</strong> pfSense and OPNsense are open-source firewall/router distributions that turn commodity x86 hardware into a full-featured network gateway. They’re not just VPN software; they’re complete network operating systems.</p><p><strong>How it works:</strong> You deploy pfSense or OPNsense on a small physical box (or VM) at your office gateway. From the web UI, you configure WireGuard, OpenVPN, or IPSec VPN servers, along with firewall rules, VLAN segmentation, DNS, DHCP, and traffic shaping, all in one place.</p><p><strong>Best use case:</strong> Companies that want a single, unified appliance managing the entire office network perimeter, with VPN built in.</p><p><strong>Pros:</strong> Full network visibility and control, supports multiple VPN protocols simultaneously, strong community and documentation, hardware options from cheap mini PCs to purpose-built appliances.</p><p><strong>Cons:</strong> Requires dedicated hardware, more involved initial setup, steeper learning curve than software-only solutions.</p><p><strong>Cost:</strong> Both are free and open source. Commercial support plans available for pfSense+ (Netgate).</p><h3><strong>5. Solution Comparison at a Glance</strong></h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SqLailpd57FM3lLLJzoNqQ.png" /></figure><blockquote><strong>Note on pfSense/OPNsense and CGNAT:</strong> pfSense and OPNsense do not inherently require a static IP address. The real constraint is inbound reachability. If your office sits behind CGNAT or a dynamic IP, you can still use these platforms by combining them with Dynamic DNS (DDNS) to track IP changes, WireGuard’s built-in roaming support, Tailscale integration directly on the pfSense box, or a Pangolin reverse tunnel for services that cannot accept inbound connections.</blockquote><h3>6. Recommended Combinations by Company Size</h3><h3>Solo Developer / Freelancer</h3><p><strong>Recommended: WireGuard (self-managed)</strong></p><p>Install WireGuard on your home or office router (or a small Raspberry Pi). Add a peer config for each of your devices. Total cost: zero. Total setup time: about an hour the first time.</p><p>If your ISP uses CGNAT: switch to <strong>Tailscale</strong> on the free tier. It handles peer discovery automatically and you’ll have a working tunnel in under 15 minutes.</p><h3>Small Office (5–20 Users)</h3><p><strong>Recommended: Tailscale + subnet routing, or pfSense with WireGuard</strong></p><p>With Tailscale, install the client on a server inside the office, enable subnet routing to expose 192.168.1.0/24 (or your local range), and all remote users can reach internal resources through that one device. No firewall changes needed.</p><p>For more control, or if you have a static IP and prefer on-premise everything, deploy OPNsense on a $150 mini PC at your office gateway and configure WireGuard from the GUI. You get firewall rules, VPN, DNS, and traffic monitoring in one box.</p><h3>Medium Company (20–100 Users)</h3><p><strong>Recommended: pfSense/OPNsense + WireGuard, with Pangolin for CGNAT fallback</strong></p><p>At this scale, you want centralized management and auditability. A pfSense or OPNsense deployment gives you per-user VPN certificates, firewall segmentation (so remote users only reach what they’re supposed to), and logging.</p><p>If some branch offices or remote servers sit behind CGNAT and can’t accept inbound connections, deploy Pangolin on a small VPS as a relay. Internal servers at those locations connect outbound to the relay; your VPN gateway routes traffic accordingly.</p><p>For web-facing internal tools (internal HR portals, ERP web interfaces), add Cloudflare Tunnel in front of those specific services rather than routing everything through the VPN.</p><h3>7. Security Considerations</h3><p>Getting the tunnel up is only half the job. Here’s what actually keeps it secure:</p><p><strong>Certificate-based authentication over passwords.</strong> WireGuard does this by design (public key pairs). For OpenVPN, generate a certificate authority and issue individual client certificates. Never rely on username/password alone. A stolen password opens the door; a stolen certificate is generally harder to abuse because it requires access to the registered device or its stored key material, though it is not immune to exfiltration by malware or extraction from unencrypted storage.</p><p><strong>Device whitelisting.</strong> Only devices with a registered public key (WireGuard) or certificate (OpenVPN) should be able to connect. If an employee leaves, revoke their certificate or remove their peer entry immediately. Don’t wait.</p><p><strong>Avoid open ports where possible.</strong> If you can use a reverse tunnel architecture (Cloudflare Tunnel, Pangolin), prefer it for externally exposed services. Fewer open inbound ports means a smaller attack surface. WireGuard’s UDP port is the minimum you need for direct VPN; protect it with firewall rules that rate-limit connection attempts.</p><p><strong>DNS verification for split tunneling.</strong> When users connect to the VPN, make sure internal DNS resolution works correctly. If your internal ERP runs on erp.company.local, the VPN client needs to use your internal DNS server, not 8.8.8.8. Configure this in the WireGuard DNS = field or OpenVPN&#39;s dhcp-option DNS.</p><p><strong>Keep private keys on the device.</strong> WireGuard private keys and OpenVPN certificates should live only on the client device, not in cloud storage, not in a shared folder, not in email. Generate keys on the device when possible. If you’re distributing config files, use a secure channel and delete them from the distribution location once deployed.</p><p><strong>Layer MFA on top of certificates.</strong> Certificate-based authentication is strong, but the most resilient setups add Multi-Factor Authentication (MFA) as a second layer. Tailscale supports MFA through its SSO integration with identity providers like Google Workspace, Okta, and Azure AD. Cloudflare Access supports MFA natively through its identity-aware proxy. OpenVPN Access Server supports TOTP (Google Authenticator-style codes) and RADIUS-based MFA. For raw WireGuard, MFA is not built in, but you can place an identity-aware reverse proxy such as Authelia or Authentik in front of internal services as a compensating control. The principle is straightforward: a certificate proves the device is known; MFA proves the person holding the device is who they claim to be. Both layers together are significantly harder to compromise than either alone.</p><p><strong>Endpoint hygiene is not optional.</strong> No VPN architecture compensates for compromised endpoints. Patch management, full-disk encryption, and endpoint protection on every device that connects to your network are not extras ,they are the foundation that everything else sits on. A perfectly configured WireGuard tunnel is only as secure as the laptop on the other end of it. Log all VPN connections. Review who connected, from where, and for how long. Rotate certificates annually or when personnel changes occur.</p><p><strong>Audit and rotate.</strong> Log all VPN connections. Review who connected, from where, and for how long. Rotate certificates annually or when personnel changes occur.</p><h3>8. Conclusion</h3><p>Secure remote access to an on-premise network doesn’t require a cloud platform, a six-figure budget, or a dedicated networking team.</p><p>It helps to understand why that statement is true in 2025 in a way it wasn’t even five years ago. The term “open-source ecosystem” refers to the collection of freely available, community-developed tools that now cover every layer of the remote access stack. At the protocol layer, WireGuard (merged into the Linux kernel in 2020) replaced the aging OpenVPN as the modern default, delivering far better performance and a much smaller attack surface. At the management layer, platforms like OPNsense and pfSense matured into full-featured network operating systems with polished web interfaces, rivaling expensive commercial appliances. Tailscale (launched in 2019) solved WireGuard’s key distribution complexity by wrapping it in a zero-configuration coordination layer, and Headscale later made even that coordination server self-hostable. At the tunneling layer, Cloudflare Tunnel and self-hosted alternatives like Pangolin solved the CGNAT problem by reversing the connection direction entirely. All three layers reached production-grade maturity together within the last few years, which is why the combination is now genuinely viable for production use without any commercial licensing.</p><p><strong>Start simple.</strong> If you have a static public IP and a technical team, WireGuard is the right answer: fast, modern, zero licensing cost. If you’re dealing with CGNAT or want something operational in under an hour, Tailscale removes all the friction.</p><p><strong>Add structure as you grow.</strong> When user count climbs or compliance requirements appear, anchor your setup on pfSense or OPNsense. These platforms give you the management plane (logging, firewall segmentation, certificate management) that manual WireGuard configs can’t easily provide.</p><p><strong>Use the right tool for each access pattern.</strong> VPNs are excellent for full network access (RDP, SMB, database connections). Reverse tunnels like Cloudflare Tunnel or Pangolin are better for exposing specific web applications without opening firewall ports. A mature setup often uses both, side by side.</p><p>The instinct to reach for a managed cloud platform is understandable, because it promises simplicity. But for most on-premise environments, that simplicity comes with unnecessary cost, external data routing, and vendor lock-in. The solutions described here give you comparable security posture, significantly more control, and infrastructure that you actually own.</p><p>Start with WireGuard. Add Tailscale if you hit CGNAT. Graduate to pfSense when you need central management. That progression covers the vast majority of real-world scenarios.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=92b163d3d69d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Publishing AL Extensions to a Local Business Central Container Using Visual Studio Code]]></title>
            <link>https://albertassaad.medium.com/publishing-al-extensions-to-a-local-business-central-container-using-visual-studio-code-152322bfe181?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/152322bfe181</guid>
            <category><![CDATA[visual-studio-code]]></category>
            <category><![CDATA[business-central]]></category>
            <category><![CDATA[microsoft-dynamics-365]]></category>
            <category><![CDATA[al-publisher]]></category>
            <category><![CDATA[developmental]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Fri, 08 May 2026 09:52:35 GMT</pubDate>
            <atom:updated>2026-05-08T09:52:35.150Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_ZZXEicaX2V6GA5rxy9-hw.png" /></figure><p>This is the third article in the Business Central local development series.</p><p><a href="https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6"><strong>Part 1</strong></a> covered setting up a Business Central sandbox container on Windows using Docker and BcContainerHelper. <a href="https://medium.com/@albertassaad/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0"><strong>Part 2</strong></a> covered installing Visual Studio Code, pulling the AL Language VSIX from the container, and scaffolding a fresh AL project.</p><p>At this point you have a running bcserver container and an AL project open in VS Code. The project contains three files: app.json, .vscode/launch.json, and HelloWorld.al. Everything is in place the only missing piece is telling VS Code <em>where</em> to publish. That&#39;s what we fix in this article.</p><p>By the end of this article, you will have downloaded symbols, compiled the HelloWorld extension, and seen it running inside your Business Central container.</p><h3>1- Understanding What launch.json Does</h3><p>Before touching any configuration, it helps to understand what launch.json is actually for.</p><p>When you press F5 in VS Code on an AL project, the AL Language extension does two things: it compiles your AL code into a .app package, and it publishes that package to a Business Central server. launch.json is the file that tells the extension <em>which</em> server to publish to, <em>how</em> to authenticate, and <em>what to do</em> after publishing.</p><p>Open .vscode/launch.json in your project. The scaffolded file looks like this:</p><pre>{<br>  &quot;version&quot;: &quot;0.2.0&quot;,<br>  &quot;configurations&quot;: [<br>    {<br>      &quot;type&quot;: &quot;al&quot;,<br>      &quot;request&quot;: &quot;launch&quot;,<br>      &quot;name&quot;: &quot;Your own server&quot;,<br>      &quot;server&quot;: &quot;http://localhost&quot;,<br>      &quot;serverInstance&quot;: &quot;BC&quot;,<br>      &quot;authentication&quot;: &quot;Windows&quot;,<br>      &quot;startupObjectId&quot;: 22,<br>      &quot;startupObjectType&quot;: &quot;Page&quot;,<br>      &quot;breakOnError&quot;: &quot;All&quot;,<br>      &quot;launchBrowser&quot;: true,<br>      &quot;enableLongRunningSqlStatements&quot;: true,<br>      &quot;enableSqlInformationDebugger&quot;: true,<br>      &quot;tenant&quot;: &quot;default&quot;<br>    }<br>  ]<br>}</pre><p>Most of these defaults are close to correct for a local container. The fields that matter most are server, serverInstance, and authentication.</p><h3>2- Configuring launch.json for Your bcserver Container</h3><p>Make the following changes to match your local setup:</p><p><strong>server</strong> :Change this to your container name:</p><pre>&quot;server&quot;: &quot;http://bcserver&quot;</pre><p>If you followed Part 1 exactly, your container is named bcserver. If you used a different name when running New-BcContainer, use that name here instead.</p><p><strong>serverInstance</strong>:Leave this as &quot;BC&quot;. That is the default instance name BcContainerHelper creates.</p><p><strong>authentication</strong>:Change this to &quot;UserPassword&quot;:</p><pre>&quot;authentication&quot;: &quot;UserPassword&quot;</pre><p>Windows authentication works only when the machine running VS Code is joined to the same domain as the container, which is rarely the case in a local dev setup. UserPassword is the right choice for container-based development it will prompt you for the credentials you created in <a href="https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6">Part 1</a>.</p><p><strong>startupObjectId and </strong><strong>startupObjectType</strong>: These control which page opens in the browser after publishing. The scaffolded values (22, Page) point to the Customer List, which is exactly what HelloWorld.al extends, so leave them as-is.</p><p>Your final launch.json should look like this:</p><pre>{<br>  &quot;version&quot;: &quot;0.2.0&quot;,<br>  &quot;configurations&quot;: [<br>    {<br>      &quot;type&quot;: &quot;al&quot;,<br>      &quot;request&quot;: &quot;launch&quot;,<br>      &quot;name&quot;: &quot;bcserver&quot;,<br>      &quot;server&quot;: &quot;http://bcserver&quot;,<br>      &quot;serverInstance&quot;: &quot;BC&quot;,<br>      &quot;authentication&quot;: &quot;UserPassword&quot;,<br>      &quot;startupObjectId&quot;: 22,<br>      &quot;startupObjectType&quot;: &quot;Page&quot;,<br>      &quot;breakOnError&quot;: &quot;All&quot;,<br>      &quot;launchBrowser&quot;: true,<br>      &quot;enableLongRunningSqlStatements&quot;: true,<br>      &quot;enableSqlInformationDebugger&quot;: true,<br>      &quot;tenant&quot;: &quot;default&quot;<br>    }<br>  ]<br>}</pre><p>Save the file.</p><h3>3- What Are Symbols and Why Do You Need Them</h3><p>Before the AL compiler can build your extension, it needs to know about every object in Business Central every table, page, codeunit, and enum that your code might reference. That metadata is packaged into .app files called <strong>symbols</strong>.</p><p>Think of symbols the way a C compiler thinks about header files. Your code says extends &quot;Customer List&quot; but the compiler needs to know what fields, actions, and properties the Customer List page already has before it can validate your extension. Symbols provide exactly that.</p><p>There are two symbol packages every AL project depends on:</p><ul><li><strong>System.app: </strong>the AL system library (text, integer, list types, and built-in functions)</li><li><strong>Application.app: </strong>the full Business Central base application (all the standard tables and pages)</li></ul><p>Both live on your bcserver container. The AL extension can download them automatically.</p><h3>4- Downloading Symbols</h3><p>With launch.json saved and the container running, press Ctrl+Shift+P to open the Command Palette and type:</p><pre>AL: Download Symbols</pre><p>Press Enter.</p><p>VS Code will ask which configuration to use: select the bcserver one you just configured. It will then prompt for credentials. Enter the admin username and password you set up in Part 1.</p><p>The AL extension connects to your container, pulls down the symbol packages, and stores them in the .alpackages folder inside your project directory. You will see that folder appear in the Explorer panel with two .app files inside.</p><p>Once the download completes, the red squiggles in HelloWorld.al will disappear. The compiler now knows what Customer List is.</p><h3>5- A Quick Look at HelloWorld.al</h3><p>Before publishing, open HelloWorld.al and change the code as follows:</p><pre>pageextension 50100 CustomerListExt extends &quot;Customer List&quot;<br>{<br>    actions<br>    {<br>        addlast(processing)<br>        {<br>            action(SayHello)<br>            {<br>                ApplicationArea = All;<br>                trigger OnAction()<br>                begin<br>                    Message(&#39;App published: Hello world!&#39;);<br>                end;<br>            }<br>        }<br>    }<br>}</pre><p>This is a pageextension object one of the most common AL object types. It extends the standard Customer List page (object ID 22) and adds a new action called SayHello to the processing action group. When clicked, the action shows a simple message dialog.</p><p>The object ID 50100 sits in the range you defined in app.json during Part 2. That range is what BC uses to distinguish your custom objects from Microsoft&#39;s base objects, which occupy the lower ID ranges.</p><h3>6- Publishing the Extension</h3><p>Everything is now in place. Press F5.</p><p>VS Code will:</p><ol><li>Compile HelloWorld.al into a .app package</li><li>Connect to bcserver using the credentials you enter</li><li>Upload and install the package on the container</li><li>Open your default browser and navigate to the Customer List page inside Business Central</li></ol><p>When the Customer List loads, click the <strong>Process</strong> menu in the ribbon. You will see a new action listed there. Click it. A dialog appears:</p><p><strong>“App published: Hello world!”</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kNQKYv2RLDnzQEB15f150Q.png" /></figure><p>That is your extension running inside a live Business Central container on your local machine.</p><h3>7- What Happens Under the Hood</h3><p>It is worth understanding what BC actually did when you pressed F5, because this same mechanism applies to every extension you will publish from now on.</p><p>The AL extension compiled your code into a signed .app file and sent it to the BC server via the development endpoint (port 7049 by default). The server installed the extension into the tenant, which means it ran the extension&#39;s install trigger (none in this case), registered the new objects in the system tables, and merged your page extension into the Customer List.</p><p>This is a <strong>development-mode publish</strong> it skips the normal extension lifecycle checks and installs directly into the default tenant. That is why it is fast. In a production deployment you would go through the extension marketplace or an administrative publish, but for local development this is exactly the right workflow.</p><h3>Wrapping Up</h3><p>At this point you have a complete, working local Business Central development environment:</p><ul><li>A bcserver container running a full BC sandbox</li><li>VS Code with the version-matched AL Language extension</li><li>A configured launch.json pointing at the container</li><li>Symbols downloaded and the compiler happy</li><li>A published extension you can see and interact with inside BC</li></ul><p>From here, every development cycle is the same loop: edit AL code, press F5, test in the browser. That tight loop is what makes local container development so much faster than publishing to a cloud sandbox every time you want to test a change.</p><p>That’s all for this article. Your claps and shares help this work reach more readers.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=152322bfe181" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Setting Up Visual Studio Code and Creating Your First AL Project for Business Central]]></title>
            <link>https://albertassaad.medium.com/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/c6c12482d3f0</guid>
            <category><![CDATA[developmental]]></category>
            <category><![CDATA[visual-studio-code]]></category>
            <category><![CDATA[business-central]]></category>
            <category><![CDATA[dynamics-nav]]></category>
            <category><![CDATA[microsoft-dynamics-365]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Mon, 27 Apr 2026 08:54:10 GMT</pubDate>
            <atom:updated>2026-05-08T10:05:18.558Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WDQbUlCVxgzD-ojF" /><figcaption>Your First AL Project in Business Central</figcaption></figure><p>In the <a href="https://medium.com/@albertassaad/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6">previous article</a> we set up a Business Central sandbox container on our local machine using Docker and BcContainerHelper. We now have a running bcserver container accessible through the browser, but a running server is only half of the development environment. The other half is the tooling we use to actually write AL code and that&#39;s what this article is about.</p><p>By the end of this walkthrough, you will have Visual Studio Code installed, the AL Language extension pulled directly from your own container, and a fresh AL project ready to be extended. In the next article we will start building an actual solution inside that project and publish it to the bcserver we set up.</p><p>Let’s get into it.</p><h3>1- Installing Visual Studio Code</h3><p>Visual Studio Code is the official IDE for AL development. It’s free, lightweight, and Microsoft ships the AL Language extension specifically for it there is no supported alternative, so this is the tool we use.</p><p>Go to the official download page:</p><p>👉 <a href="https://code.visualstudio.com/Download">https://code.visualstudio.com/Download</a></p><p>Pick the <strong>Windows</strong> installer (the <strong>User Installer</strong>, 64-bit is the right choice for most machines). The User Installer doesn’t require admin rights and keeps the installation isolated to your user profile, which is usually what you want on a development machine.</p><p>Run the installer and go through the wizard. A few options I always tick on the “Select Additional Tasks” screen:</p><ul><li><strong>Add “Open with Code” action to Windows Explorer file context menu</strong></li><li><strong>Add “Open with Code” action to Windows Explorer directory context menu</strong></li><li><strong>Register Code as an editor for supported file types</strong></li><li><strong>Add to PATH</strong></li></ul><p>The first two are huge time-savers you can right-click any folder and open it directly in VS Code. The last one lets you launch VS Code from PowerShell with the code command, which we will use shortly.</p><p>Once the installation finishes, launch VS Code to confirm everything works.</p><h3>2- Why We Pull the VSIX from bcserver (and Not from the Marketplace)</h3><p>This is the part most newcomers get wrong, so it’s worth a short paragraph.</p><p>You can install the AL Language extension directly from the VS Code Marketplace, and for general learning that’s fine. But when you are working with a <strong>specific Business Central version</strong> which is exactly our situation, because we built the container against a specific sandbox artifact the AL compiler version has to match the platform version of that container. If the versions drift, you get cryptic compilation errors, missing symbols, or publish failures that are painful to debug.</p><p>The cleanest way to guarantee a version match is to install the .vsix file that ships <em>with</em> the container itself. Every BC container exposes its own matching AL Language extension at a known URL, so we just grab that one.</p><h3>3- Downloading the VSIX from bcserver</h3><p>With the container running, open any browser and navigate directly to:</p><pre>http://bcserver:8080/ALLanguage.vsix</pre><p>(If you named your container something other than bcserver, replace that part with your container name.)</p><p>The browser will immediately start downloading a file named ALLanguage.vsix. Save it somewhere easy to reach your <strong>Downloads</strong> folder is perfectly fine. This is the AL Language extension packaged specifically for the BC version running inside your container, so the compiler and symbols will always match.</p><p>That’s the file we will install into VS Code.</p><h3>4- Installing the VSIX in Visual Studio Code</h3><p>There are two ways to install a local VSIX. Both work; pick whichever you prefer.</p><p><strong>Option A : Through the VS Code UI:</strong></p><ol><li>Open VS Code</li><li>Click the <strong>Extensions</strong> icon in the left sidebar (or press Ctrl+Shift+X)</li><li>Click the <strong>three-dot menu (⋯)</strong> in the top-right of the Extensions panel</li><li>Choose <strong>Install from VSIX…</strong></li><li>Browse to the ALLanguage.vsix file you downloaded and click <strong>Install</strong></li></ol><p><strong>Option B : Through the command line (my preferred way):</strong></p><p>Open PowerShell in the folder where you saved the VSIX and run:</p><pre>code --install-extension ALLanguage.vsix</pre><p>This is the fastest method, and it’s also handy when you’re scripting a new developer machine setup.</p><p>Either way, VS Code will confirm that the extension has been installed. Restart VS Code once to make sure the extension loads cleanly.</p><h3>5- Verifying the Extension Is Enabled</h3><p>Go back to the Extensions panel (Ctrl+Shift+X) and type <strong>AL Language</strong> in the search box. You should see it listed under <strong>Installed</strong>, with an <strong>Enabled</strong> status. If for some reason it shows as <strong>Disabled</strong>, click the small gear icon and choose <strong>Enable</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yEm_67AQI1ljWEuY7OYF8w.png" /></figure><p>While you’re there, also check that you don’t have a second AL Language extension installed from the Marketplace. Having two versions installed at the same time causes odd behavior the editor sometimes loads the wrong compiler, and IntelliSense gets confused. If you do see two, disable the Marketplace one and keep only the one from the VSIX.</p><h3>6- Creating Your First AL Project</h3><p>Now for the fun part. With the extension enabled, we can scaffold a new AL project in seconds.</p><ol><li>Open VS Code</li><li>Press Ctrl+Shift+P to open the <strong>Command Palette</strong></li><li>Type <strong>AL: Go!</strong> and press Enter</li><li>VS Code will ask you to pick a <strong>target folder</strong> for the new project create an empty folder somewhere on disk (something like C:\ALProjects\MyFirstExtension) and select it</li><li>It will then ask for the <strong>target platform</strong>. Pick the one that matches your container for a modern BC sandbox, choose <strong>Microsoft cloud sandbox (latest)</strong> or the version-specific option matching your container in our case <strong>Your own Server BCServer</strong>.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uIKFbZsDueZrnYMxQkydRQ.png" /></figure><p>VS Code will generate a fresh AL project inside that folder, containing:</p><ul><li><strong>app.json</strong> the manifest of your extension (name, publisher, version, dependencies, id ranges)</li><li><strong>.vscode/launch.json</strong> the configuration that tells AL where to publish your extension</li><li><strong>HelloWorld.al</strong> a sample page extension that adds a &quot;Hello World&quot; action to the Customer List</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UfaMaMRXNrrlcjSUBpMX7w.png" /></figure><p>Open HelloWorld.al and take a look. This is the canonical &quot;hello world&quot; for AL: a pageextension object that adds an action to the Customer List page and pops up a message when clicked. Don&#39;t run it yet we still need to configure launch.json to point to our bcserver container, which is exactly what we will cover in the next article.</p><h3>Wrapping Up</h3><p>At this point we have VS Code installed, the AL Language extension pulled from our own container and enabled, and a fresh AL project scaffolded on disk. This is the minimum working setup any BC developer needs before writing a single line of AL.</p><p>In the <strong>next article</strong>, we will open launch.json, point it at our bcserver container, download the <strong>symbols</strong>, make a small change to the sample HelloWorld.al object, and <strong>publish</strong> the extension to the container so we can see it running inside Business Central. That&#39;s where it starts to feel like actual development.</p><p>That’s all for this article. Your claps and shares help this work reach more readers.</p><p><a href="https://medium.com/@albertassaad/publishing-al-extensions-to-a-local-business-central-container-using-visual-studio-code-152322bfe181"><strong>Continue to Part 3</strong></a><strong>:</strong> In the next article, we configure launch.json to point at our bcserver container, download the symbols the compiler needs, and publish the HelloWorld extension so we can see it running live inside Business Central.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c6c12482d3f0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How I Set Up a Business Central Dev Container on Windows (Step-by-Step)]]></title>
            <link>https://albertassaad.medium.com/setting-up-a-microsoft-dynamics-365-business-central-sandbox-container-on-windows-for-local-778b7319c3b6?source=rss-5b48dd238294------2</link>
            <guid isPermaLink="false">https://medium.com/p/778b7319c3b6</guid>
            <category><![CDATA[docker]]></category>
            <category><![CDATA[dynamics-365]]></category>
            <category><![CDATA[developmental]]></category>
            <category><![CDATA[business-central]]></category>
            <category><![CDATA[microsoft-dynamics]]></category>
            <dc:creator><![CDATA[Albert Assaad]]></dc:creator>
            <pubDate>Mon, 20 Apr 2026 08:32:28 GMT</pubDate>
            <atom:updated>2026-04-27T09:20:31.565Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*njDXYtqIM5R34yM09hznOw.png" /><figcaption>Generated by ChatGpt</figcaption></figure><p>After spending some time working with Microsoft Dynamics 365 Business Central, I wanted to write down the exact steps I use to spin up a local sandbox container on Windows.</p><p>In this article we will go through the full setup: prerequisites, Docker Desktop, enabling Windows features, installing BcContainerHelper, building the container, and accessing Business Central in the browser. In the next article we will install Visual Studio Code and configure it to program and publish our AL extension to this BC server.</p><p>Let’s begin.</p><p><strong>1- Prerequisites:</strong></p><p>Before we start, we need to make sure the machine can actually run Windows containers. Business Central containers are Windows containers, not Linux ones, so the host OS matters here.</p><p>a- <strong>Windows Edition:</strong> Windows 10 or 11 Pro, Enterprise, or Education. Home edition does not support Hyper-V or Windows Containers out of the box.</p><p>b- <strong>RAM:</strong> At least 16GB is recommended, because we will dedicate 8GB to the container itself and the rest goes to the host and your tools.</p><p>c- <strong>Disk Space:</strong> 50GB+ free on an SSD. The BC artifact alone is around 8GB and Docker images pile up quickly.</p><p>d- <strong>PowerShell:</strong> Administrator access to PowerShell is required for pretty much every step below.</p><p><strong>2- Installing Docker Desktop:</strong></p><p>Docker Desktop is what actually runs the container. We will install it first and switch it to Windows containers mode.</p><p>a- <strong>Download:</strong> Get the installer from <a href="https://www.docker.com/get-started/">https://www.docker.com/get-started/</a></p><p>b- <strong>Install:</strong> Run the installer and complete the setup. A restart is usually needed at the end.</p><p>c- <strong>WSL update:</strong> If Docker is using the WSL (Windows Subsystem for Linux) backend, run this in PowerShell:</p><pre>wsl --update</pre><p>d- <strong>Switch to Windows containers:</strong> Right-click the Docker tray icon in the system tray and choose “Switch to Windows containers”. This is important BC will not run on Linux containers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XCkY2xWX1n9DP5gnWJe4BA.png" /></figure><p><strong>3- Enabling Required Windows Features:</strong></p><p>Even with Docker installed, Windows still needs Hyper-V and the Containers feature turned on.</p><p>a- <strong>Add Hyper-V:</strong> Open “Turn Windows features on or off” and enable Hyper-V there, or do it from PowerShell in the next step.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/415/1*P4XjOlnKe2TKCitSCjJtJw.png" /></figure><p>b- <strong>Open PowerShell as Administrator</strong> and run:</p><pre>Enable-WindowsOptionalFeature -Online -FeatureName $(&quot;Microsoft-Hyper-V&quot;, &quot;Containers&quot;) -All</pre><p>c- <strong>Restart the computer.</strong> This is required, the features will not be fully active until you reboot.</p><p><strong>4- Installing BcContainerHelper:</strong></p><p>BcContainerHelper is a PowerShell module (maintained by Freddy Kristiansen from Microsoft) that wraps the raw Docker commands into BC-friendly cmdlets like New-BcContainer, Get-BcContainerAppInfo, Publish-BcContainerApp, and many more. You can do everything with plain docker commands, but it takes a lot more work.</p><p>Open PowerShell as Administrator and run:</p><pre>Install-Module BcContainerHelper -Force</pre><p>The -Force flag skips the confirmation prompts and also overwrites older versions if any exist.</p><p><strong>5- Creating the Business Central Container:</strong></p><p>This is the main step. Before we run the command, there is one concept worth explaining.</p><p><strong>Artifact URL:</strong> The artifact URL is a pointer to a specific BC version and localization (country). Microsoft publishes BC artifacts for each country (US, DE, FR, W1, etc.) and each version. Instead of hardcoding a URL, we use Get-BCArtifactUrl to always pull the latest one. For example, Get-BCArtifactUrl -type sandbox -country w1 -select Latest returns the latest worldwide (W1) sandbox artifact. If you want the US localization you would use -country us, and so on.</p><p>Now the full command:</p><pre>New-BcContainer `<br>    -containerName bcserver `<br>    -accept_eula `<br>    -accept_outdated `<br>    -auth NavUserPassword `<br>    -Credential (New-Object PSCredential -ArgumentList &quot;admin&quot;, (ConvertTo-SecureString &quot;Admin123!&quot; -AsPlainText -Force)) `<br>    -artifactUrl (Get-BCArtifactUrl -type sandbox -country w1 -select Latest) `<br>    -enableApiServices `<br>    -isolation process `<br>    -memoryLimit 8G `<br>    -useSSL:$false `<br>    -updateHosts `<br>    -locale &quot;en-US&quot;</pre><p>Let’s go through the important parameters:</p><p>a- <strong>containerName:</strong> The name assigned to the Docker container. We use “bcserver”, which is also the hostname we will browse to later.</p><p>b- <strong>auth NavUserPassword:</strong> Uses username/password authentication instead of Windows authentication. Easier for local development.</p><p>c- <strong>Credential:</strong> The admin username and password for BC. Here it is “admin” / “Admin123!”. Change this to something stronger if you are not on a throwaway dev machine.</p><p>d- <strong>artifactUrl:</strong> As explained above, this pulls the latest W1 sandbox artifact.</p><p>e- <strong>isolation process:</strong> Uses process isolation instead of Hyper-V isolation. It uses less memory and starts faster, but it only works when the host Windows version matches the container Windows version. If you get an isolation error, switch this to hyperv.</p><p>f- <strong>memoryLimit 8G:</strong> The minimum you really want for BC to run properly. Less than this and the service will struggle.</p><p>g- <strong>useSSL false:</strong> Skips the SSL certificate setup. Fine for local development, not for anything production-like.</p><p>h- <strong>updateHosts:</strong> Adds “bcserver” to the Windows hosts file so you can browse to http://bcserver/... by name instead of by IP.</p><p>The first time you run this, it will take time ,the artifact is around 8GB and the container has to initialize the SQL database, the BC service tier, and the web client. Once you see “<strong>Ready for connections!</strong>” in the output, the container is up.</p><p>If your internet connection is limited, the download can take a long time and sometimes times out mid-way. A workaround I use is to grab the artifact URLs from PowerShell and pass them to a proper download manager. Run this to get first URLs just replace the end of it from W1 with platform:</p><pre>Get-BCArtifactUrl -type sandbox -country w1 -select Latest</pre><p>The first URL points to the <strong>W1 artifact</strong> (the localization and demo data) and the second one points to the <strong>platform artifact</strong> (the BC service, web client, and runtime). Both are .zip files. Copy the two URLs, paste them into your download manager (IDM, Free Download Manager, whatever you use), and let it resume as needed until both files are fully downloaded.</p><p>Once you have the two zip files, we need to extract them into the BcContainerHelper cache folder, which is C:\bcartifacts.cache\ by default. The folder structure has to match exactly what BcContainerHelper expects, otherwise it will just redownload everything. Check the version number in the URL (something like 28.0.46665.49267) and create the folders like this:</p><ul><li>Extract the <strong>W1 zip</strong> content into: C:\bcartifacts.cache\sandbox\&lt;version&gt;\w1\</li><li>Extract the <strong>platform zip</strong> content into: C:\bcartifacts.cache\sandbox\&lt;version&gt;\platform\</li></ul><p>Make sure you extract the <em>content</em> of the zip (the files inside) into those folders, not the zip folder itself ,a common mistake is ending up with C:\bcartifacts.cache\sandbox\&lt;version&gt;\w1\w1\... which BcContainerHelper will not recognize.</p><p>After the files are in place, run the New-BcContainer command as before. BcContainerHelper will detect the cached artifacts and skip the download entirely, jumping straight to the container build.</p><p>You can always see the container in Docker Desktop Application under Containers, you can stop it ,start it and delete it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_qTXJcB1RBo5GPZmrIoUYg.png" /></figure><p><strong>6- Accessing Business Central:</strong></p><p>a- <strong>Open Microsoft Edge.</strong> An InPrivate window is recommended for the first login so cached credentials do not get in the way.</p><p>b- <strong>Navigate to:</strong> <a href="http://bcserver/BC/?tenant=default">http://bcserver/BC/?tenant=default</a></p><p>c- <strong>Login</strong> with username admin and password Admin123!or the password you inserted in the -Credential parameter when you created the container</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/666/1*adbxEXtJoD_IM2Az8ZZ3OQ.png" /></figure><p>d- <strong>First load:</strong> This can take 5 to 10 minutes while the CRONUS demo company initializes. Do not refresh the page it makes things worse and you will end up waiting even longer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/774/1*752jhGuBg3SYfxx4-_715Q.png" /></figure><p>e- <strong>Role Center:</strong> Once it loads, you will land on the CRONUS International Ltd. demo company Role Center, and from there you have a fully working BC sandbox to play with.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/958/1*8ZbHn8CAVODxXBzsCJCI1A.png" /></figure><h3>7- Useful Container Management Commands:</h3><p>Here are the commands I end up using the most:</p><p>a- <strong>List running containers:</strong></p><pre>docker ps</pre><p>b- <strong>Check container stats (CPU, memory):</strong></p><pre>docker stats bcserver --no-stream</pre><p>c- <strong>View container logs:</strong></p><pre>docker logs bcserver</pre><p>d- <strong>Stop the container:</strong></p><pre>docker stop bcserver</pre><p>e- <strong>Start the container again:</strong></p><pre>docker start bcserver</pre><p>f- <strong>Remove the container</strong> (when you want to rebuild from scratch):</p><pre>Remove-BcContainer -containerName bcserver</pre><p>Remove-BcContainer is the BcContainerHelper way of doing it, and it cleans up the hosts file entry and other bits that plain docker rm leaves behind.</p><p>At this point we have a running Business Central sandbox on the local machine, accessible through the browser, with an admin account ready to go. In the next article we will install Visual Studio Code, set up the AL Language extension, and configure launch.json so we can write AL code and publish our extension directly to this bcserver container.</p><p>That’s all for this article. Your claps and shares help this work reach more readers.</p><p><strong>Continue to Part 2:</strong> <a href="https://albertassaad.medium.com/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0">https://albertassaad.medium.com/setting-up-visual-studio-code-and-creating-your-first-al-project-for-business-central-c6c12482d3f0</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=778b7319c3b6" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>