{"title":"Create a new module in the System Application","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-new-module/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-new-module, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-new-module","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to create a new module in the System Application.","date":"2026-10-29","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Create a new module in the System Application","slug":"create-a-new-module-in-the-system-application","at":0,"chars":9461},{"level":2,"title":"Requirements","slug":"requirements","at":137,"chars":698},{"level":2,"title":"Create a new module","slug":"create-a-new-module","at":835,"chars":7858},{"level":3,"title":"Set Up Visual Studio Code for module development","slug":"set-up-visual-studio-code-for-module-development","at":1445,"chars":508},{"level":3,"title":"Create a branch","slug":"create-a-branch","at":1953,"chars":145},{"level":3,"title":"Add the new module","slug":"add-the-new-module","at":2098,"chars":6595},{"level":4,"title":"Commit and push your changes and open a PR","slug":"commit-and-push-your-changes-and-open-a-pr","at":8355,"chars":338},{"level":2,"title":"Related information","slug":"related-information","at":8693,"chars":768}],"text":"# Create a new module in the System Application\nThis topic provides an overview of how to create a new module in the System Application.\n## Requirements\n1. Familiarity with development in AL. See AL Development<devenv-get-started>.\n2. Your development environment is ready. See Set Up an Environment for Developing a Module<devenv-set-up-an-environment>.\n3. Obtain Microsoft's approval for the related GitHub issue before opening a contribution pull request (PR). Follow the BCApps contribution guidelines<https://github.com/microsoft/BCApps/blob/main/CONTRIBUTING.md>.\n> NOTE\n> Your environment must have the correct symbols. Go get those, in Visual Studio Code, select F1>/kbd>, and then choose AL: Download Symbols. Also, make a note of the server and serverInstance settings. You will add that information to the launch.json file.\n## Create a new module\nThe following sections provide an example of how to contribute a new module. The example is based on the XmlWriter module, which was published in the legacy ALAppExtensions repository. That contribution added a wrapper module to provide support for the XmlWriter, and the steps in this topic will recreate the pull request for the XmlWriter module. If you want to view the original pull request, it's available here: Pull Request 7876<https://github.com/microsoft/ALAppExtensions/pull/7876>.\nFor new contributions, please refer to BCApps repository<https://github.com/microsoft/BCApps>.\n### Set Up Visual Studio Code for module development\nOpen the launch.json, file and update the server, serverInstance, and authentication settings, as described in Set Up Your Development Environment<devenv-set-up-an-environment>.\n```json\n\n    \"server\": \"http://YourDockerContainerName\",\n    \"serverInstance\": \"BC\",\n    \"authentication\": \"UserPassword\",\n\n```\nOpen the settings.json file, and update the al.assemblyProbingPaths, as described in Set Up a Development Environment<devenv-set-up-an-environment>.\n### Create a branch\nTo create a branch, run the git checkout -b \"YourFeatureBranchName\" command. Afterward, you can start creating a new module.\n### Add the new module\nBefore you create a new module, make sure you are familiar with the general architecture of system modules. See Module Architecture<devenv-blueprint>.\nWe'll start by creating a new folder named XmlWriter in the System folder, where we will add an app.json file. The app.json file will contain the general details of the module.\n```json\n    {\n        \"id\":  \"215b484f-9fbf-437c-bc6e-67e2c0f283b0\",\n        \"name\":  \"XMLWriter\",\n        \"publisher\":  \"Microsoft\",\n        \"brief\":  \"Write XML quickly with System.Xml.XmlTextWriter.\",\n        \"description\":  \"Provides a fast, non-cached, forward-only way to create streams or files with XML data that conforms to guidelines for W3C Extensible Markup Language (XML) 1.0 and Namespaces.\",\n        \"version\":  \"17.0.0.0\",\n        \"privacyStatement\":  \"https://go.microsoft.com/fwlink/?linkid=724009\",\n        \"EULA\":  \"https://go.microsoft.com/fwlink/?linkid=2009120\",\n        \"help\":  \"https://go.microsoft.com/fwlink/?linkid=2103698\",\n        \"url\":  \"https://go.microsoft.com/fwlink/?linkid=724011\",\n        \"logo\":  \"\",\n        \"dependencies\":  [\n            {\n                \"id\":  \"7e3b999e-1182-45d2-8b82-d5127ddba9b2\",\n                \"name\":  \"DotNet Aliases\",\n                \"publisher\":  \"Microsoft\",\n                \"version\":  \"17.0.0.0\"\n            }\n        ],\n        \"screenshots\":  [],\n        \"platform\":  \"17.0.0.0\",\n        \"idRanges\":  [\n            {\n                \"from\":  1483,\n                \"to\":  1484\n            }\n        ],\n        \"target\":  \"OnPrem\",\n        \"contextSensitiveHelpUrl\":  \"/dynamics365/business-central/\"\n    }\n```\n> NOTE\n> After we finish developing our module, we will need to update the app.json file to ensure that the versions and idRanges are correct. We can easily verify the version by checking the app.json in other modules in the System Application. The idRanges must reflect the IDs used in the module.\nNext, create the src folder under System/XmlWriter. This folder will contain our source code. We will create an internal implementation codeunit named XmlWriterImpl.Codeunit.al in the src folder.\nAfter adding the implementation functions, the implementation codeunit will look as follows.\n```al\n    codeunit 1484 \"XmlWriter Impl\"\n    {\n        Access = Internal;\n\n        procedure WriteStartDocument()\n        begin\n            StringBuilder := StringBuilder.StringBuilder();\n            StringWriter := StringWriter.StringWriter(StringBuilder);\n            XmlTextWriter := XmlTextWriter.XmlTextWriter(StringWriter);\n            XmlTextWriter.WriteStartDocument();\n        end;\n\n        procedure WriteEndDocument()\n        begin\n            XmlTextWriter.WriteEndDocument();\n        end;\n\n        procedure ToBigText(var XmlBigText: BigText)\n        begin\n            XmlTextWriter.WriteString(XmlBigText);\n        end;\n\n        var\n            StringBuilder: DotNet StringBuilder;\n            StringWriter: DotNet StringWriter;\n            XmlTextWriter: DotNet XmlTextWriter;\n    }\n```\nNow that we have created our implementation codeunit, we must add public functions in a facade codeunit with the functionality that we want to expose. Because the functions are public, we must ensure that these are tested and documented. To do this, we need to create a facade codeunit. In this example, we'll name the codeunit XmlWriter.Codeunit.al. The functions call the corresponding functions in the implementation codeunit.\nThe following is an example of the facade codeunit named XmlWriter.Codeunit.al that includes public functions and documentation.\n```al\n\n    /// <summary>\n    /// Provides helper functions for System.Xml.XmlWriter\n    /// </summary>\n    codeunit 1483 \"XmlWriter\"\n    {\n        Access = Public;\n\n        /// <summary>\n        /// Creates the XmlWriter Document\n        /// </summary>\n        procedure WriteStartDocument()\n        begin\n            XmlWriterImpl.WriteStartDocument();\n        end;\n\n        /// <summary>\n        /// Closes any open elements or attributes and puts the writer back in the Start state.\n        /// </summary>\n        procedure WriteEndDocument()\n        begin\n            XmlWriterImpl.WriteEndDocument();\n        end;\n\n        /// <summary>\n        /// Writes the text within XmlWriter to the BigText variable.\n        /// </summary>\n        /// <param name=\"XmlBigText\">The BigText the XmlWriter has to be write to.</param>\n        procedure ToBigText(var XmlBigText: BigText)\n        begin\n            Clear(XmlBigText);\n            XmlWriterImpl.ToBigText(XmlBigText)\n        end;\n\n        var\n            XmlWriterImpl: Codeunit \"XmlWriter Impl\";\n    }\n```\nNow that we have now exposed the functions, the next step is to add tests. To do that, we'll create a new folder under System Tests, XmlWriter. We will also create an app.json file for the module details and an src folder for our test code.\nWe will add the following new file under System Tests/XmlWriter/src, XmlWriterTest.Codeunit.al.\n```al\n    codeunit 139911 \"Xml Writer Test\"\n    {\n        Subtype = Test;\n\n        var\n            Assert: Codeunit \"Library Assert\";\n\n        [Test]\n        procedure TestWriteStartDocument()\n        var\n            XmlWriter: Codeunit \"XmlWriter\";\n            XmlBigText: BigText;\n        begin\n            // [GIVEN] Initialized XmlWriter\n            XmlWriter.WriteStartDocument();\n\n            // [THEN] Get XmlDocument to text\n            XmlWriter.ToBigText(XmlBigText);\n            Assert.AreEqual('<?xml version=\"1.0\" encoding=\"utf-16\"?>', Format(XmlBigText), 'Unexpected text when creating a Xml Document with XmlWriter');\n        end;\n\n        [Test]\n        procedure TestWriteEndDocumentNoElement()\n        var\n            XmlWriter: Codeunit \"XmlWriter\";\n        begin\n            // [GIVEN] Initialized XmlWriter with root element\n            XmlWriter.WriteStartDocument();\n\n            // [WHEN] Write end document\n            // [THEN] Expected error to be thrown\n            asserterror XmlWriter.WriteEndDocument();\n            Assert.ExpectedError('A call to System.Xml.XmlTextWriter.WriteEndDocument failed with this message: Document does not have a root element.');\n        end;\n    }\n```\nAfter running the tests successfully, changes are complete.\n#### Commit and push your changes and open a PR\n To commit your changes, run the git commit -m \"Your message\" command.\n To push your changes, run the git push command.\nAfter Microsoft approves the related GitHub issue, go to your GitHub fork and open a pull request in the BCApps repository. Link your pull request to the approved issue.\n## Related information\nCreate a .NET Wrapper Module<devenv-create-a-wrapper-module>\nGetting Started with Modules<devenv-getting-started>\nCreate a New Module in the System Application<devenv-new-module>\nModule Architecture<devenv-blueprint>\n\"Git\" going with extensions (requires sign in)<https://community.dynamics.com/business/b/businesscentraldevitpro/archive/2018/10/26/quot-git-quot-going-with-extensions>\nWalkthrough: Contributing to an extension on GitHub (requires sign in)<https://community.dynamics.com/business/b/businesscentraldevitpro/archive/2018/11/27/walkthrough-contributing-to-an-extension-on-github>\nBecome a Contributor to Business Central<https://cloudblogs.microsoft.com/dynamics365/no-audience/2018/08/28/become-a-contributor-to-business-central/>"}