{"title":"Change a module in the System Application","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-change-a-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-change-a-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-change-a-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 update an existing Business Central System Application module, preserve its public API, add tests, and contribute your changes to BCApps.","date":"2026-10-26","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Change a module in the System Application","slug":"change-a-module-in-the-system-application","at":0,"chars":13451},{"level":2,"title":"Prerequisites for changing a module","slug":"prerequisites-for-changing-a-module","at":323,"chars":840},{"level":2,"title":"Prepare your module development environment","slug":"prepare-your-module-development-environment","at":1163,"chars":907},{"level":2,"title":"Create a contribution branch","slug":"create-a-contribution-branch","at":2070,"chars":169},{"level":2,"title":"Historical example of changing Base64 Convert","slug":"historical-example-of-changing-base64-convert","at":2239,"chars":9976},{"level":3,"title":"Update the implementation codeunit","slug":"update-the-implementation-codeunit","at":3167,"chars":3666},{"level":3,"title":"Expose and document the public API","slug":"expose-and-document-the-public-api","at":6833,"chars":3792},{"level":3,"title":"Add tests for the changed behavior","slug":"add-tests-for-the-changed-behavior","at":10625,"chars":1590},{"level":2,"title":"Submit your module changes","slug":"submit-your-module-changes","at":12215,"chars":931},{"level":2,"title":"Related information","slug":"related-information","at":13146,"chars":305}],"text":"# Change a module in the System Application\nUpdate an existing System Application module in https://github.com/microsoft/BCApps by changing its implementation, exposing supported functionality through its public API, and adding tests. This article uses a historical Base64 Convert contribution to illustrate that workflow.\n## Prerequisites for changing a module\n Familiarity with AL development. See AL development<devenv-get-started>.\n A local clone of your BCApps fork and a development environment. Follow the current BCApps local development environment guidelines<https://github.com/microsoft/BCApps/blob/main/LOCAL_DEV_ENV.md>.\n A GitHub issue approved for contribution in BCApps before you open a pull request. Discuss your proposed change before starting implementation to avoid work that can't be accepted. Learn more in the BCApps contribution guidelines<https://github.com/microsoft/BCApps/blob/main/CONTRIBUTING.md>.\nYour changes must follow the module architecture guidelines. See Module architecture<devenv-blueprint>. Preserve the existing public API and its behavior. Run the existing tests and add tests for functionality that you change or add.\n## Prepare your module development environment\nUse the BCApps local development workflow to create a Business Central container and configure Visual Studio Code. Its setup script generates the launch.json and settings.json files for your environment. Follow the repository's current instructions rather than copying connection or assembly paths from an older example.\nOpen the module and its test project. For Base64 Convert, the folders are:\n `src\\System Application\\App\\Base64 Convert`\n `src\\System Application\\Test\\Base64 Convert`\nIf required symbols are missing, in Visual Studio Code, press F1 and select AL: Download Symbols.\nThe following historical example uses .NET interoperability. If you configure it manually, set al.assemblyProbingPaths in `.vscode/settings.json` to the required assembly locations. For current BCApps development, use the settings generated by the repository's setup script.\n## Create a contribution branch\nIn your local clone, run `git checkout -b \"<FeatureBranchName>\"`. Replace `<FeatureBranchName>` with a descriptive name for your change.\n## Historical example of changing Base64 Convert\nThe following example is based on ALAppExtensions pull request 7676<https://github.com/microsoft/ALAppExtensions/pull/7676>, which added support for text encodings other than UTF8. For a new contribution, follow the same sequence: update the implementation, expose the public API, and test the behavior.\n> IMPORTANT\n> These overloads and tests already exist. Don't add them again. The example shows the historical .NET-based implementation. The implementation changed to use the native Base64Convert system codeunit. Use the latest Base64 Convert implementation<https://github.com/microsoft/BCApps/blob/main/src/System%20Application/App/Base64%20Convert/src/Base64ConvertImpl.Codeunit.al> when preparing a new change.\nThe AL snippets are fragments from existing objects, not standalone objects. They rely on declarations, .NET aliases, and test labels in the surrounding source.\n### Update the implementation codeunit\nStart with the internal implementation codeunit. In the historical contribution, the following overloads were added to Base64ConvertImpl.Codeunit.al. The file is now under `src\\System Application\\App\\Base64 Convert\\src`.\n```al\n    procedure ToBase64(String: Text; TextEncoding: TextEncoding): Text\n    begin\n        exit(ToBase64(String, false, TextEncoding, 0));\n    end;\n\n    procedure ToBase64(String: Text; TextEncoding: TextEncoding; Codepage: Integer): Text\n    begin\n        exit(ToBase64(String, false, TextEncoding, Codepage));\n    end;\n\n    procedure ToBase64(String: Text; InsertLineBreaks: Boolean; TextEncoding: TextEncoding): Text\n    begin\n        exit(ToBase64(String, InsertLineBreaks, TextEncoding, 0));\n    end;\n\n    procedure ToBase64(String: Text; InsertLineBreaks: Boolean; TextEncoding: TextEncoding; Codepage: Integer): Text\n    var\n        Convert: DotNet Convert;\n        Encoding: DotNet Encoding;\n        Base64FormattingOptions: DotNet Base64FormattingOptions;\n        Base64String: Text;\n    begin\n        if String = '' then\n            exit('');\n\n        if InsertLineBreaks then\n            Base64FormattingOptions := Base64FormattingOptions.InsertLineBreaks\n        else\n            Base64FormattingOptions := Base64FormattingOptions.None;\n        case TextEncoding of\n            TextEncoding::UTF16:\n                Base64String := Convert.ToBase64String(Encoding.Unicode().GetBytes(String), Base64FormattingOptions);\n            TextEncoding::MSDos,\n            TextEncoding::Windows:\n                Base64String := Convert.ToBase64String(Encoding.GetEncoding(CodePage).GetBytes(String), Base64FormattingOptions);\n            else\n                Base64String := Convert.ToBase64String(Encoding.UTF8().GetBytes(String), Base64FormattingOptions);\n        end;\n\n        exit(Base64String);\n    end;\n\n    procedure FromBase64(Base64String: Text; TextEncoding: TextEncoding): Text\n    begin\n        exit(FromBase64(Base64String, TextEncoding, 1252));\n    end;\n\n    procedure FromBase64(Base64String: Text; TextEncoding: TextEncoding; CodePage: Integer): Text\n    var\n        Convert: DotNet Convert;\n        Encoding: DotNet Encoding;\n        OutputString: Text;\n    begin\n        if Base64String = '' then\n            exit('');\n\n        case TextEncoding of\n            TextEncoding::UTF16:\n                OutputString := Encoding.Unicode().GetString(Convert.FromBase64String(Base64String));\n            TextEncoding::MSDos,\n            TextEncoding::Windows:\n                OutputString := Encoding.GetEncoding(CodePage).GetString(Convert.FromBase64String(Base64String));\n            else\n                OutputString := Encoding.UTF8().GetString(Convert.FromBase64String(Base64String));\n        end;\n        exit(OutputString);\n    end;\n```\nThe encoding and decoding overloads use different default code pages. When you use MSDos or Windows, specify the same code page explicitly for both operations.\nThe existing overloads in the implementation codeunit were updated to call the new overloads with the same default encoding:\n```al\n    procedure ToBase64(String: Text): Text\n    begin\n        exit(ToBase64(String, false));\n    end;\n\n    procedure ToBase64(String: Text; InsertLineBreaks: Boolean): Text\n    begin\n        exit(ToBase64(String, InsertLineBreaks, TextEncoding::UTF8, 0));\n    end;\n\n    procedure FromBase64(Base64String: Text): Text\n    begin\n        exit(FromBase64(Base64String, TextEncoding::UTF8, 0));\n    end;\n```\nThese forwarding methods preserve the existing UTF8 defaults. When changing a module, keep existing callers in mind and use tests to check compatibility.\n### Expose and document the public API\nNext, expose the functionality through the facade codeunit and document its public procedures. In the historical contribution, the following procedures were added to Base64Convert.Codeunit.al. The file is now under `src\\System Application\\App\\Base64 Convert\\src`. Each procedure calls the corresponding implementation procedure.\nThe containing facade declares Base64ConvertImpl as a variable of type `Codeunit \"Base64 Convert Impl.\"`. Learn more in the Base64 Convert facade source<https://github.com/microsoft/BCApps/blob/main/src/System%20Application/App/Base64%20Convert/src/Base64Convert.Codeunit.al>.\n```al\n    /// <summary>\n    /// Converts the value of the input string to its equivalent string representation that is encoded with base-64 digits.\n    /// </summary>\n    /// <param name=\"String\">The string to convert.</param>\n    /// <param name=\"TextEncoding\">The TextEncoding for the input string.</param>\n    /// <returns>The string representation, in base-64, of the input string.</returns>\n    procedure ToBase64(String: Text; TextEncoding: TextEncoding): Text\n    begin\n        exit(Base64ConvertImpl.ToBase64(String, TextEncoding));\n    end;\n\n    /// <summary>\n    /// Converts the value of the input string to its equivalent string representation that is encoded with base-64 digits.\n    /// </summary>\n    /// <param name=\"String\">The string to convert.</param>\n    /// <param name=\"TextEncoding\">The TextEncoding for the input string.</param>\n    /// <param name=\"Codepage\">The Codepage if TextEncoding is MsDos or Windows.</param>\n    /// <returns>The string representation, in base-64, of the input string.</returns>\n    procedure ToBase64(String: Text; TextEncoding: TextEncoding; Codepage: Integer): Text\n    begin\n        exit(Base64ConvertImpl.ToBase64(String, TextEncoding, Codepage));\n    end;\n\n    /// <summary>\n    /// Converts the specified string, which encodes binary data as base-64 digits, to an equivalent regular string.\n    /// </summary>\n    /// <param name=\"Base64String\">The string to convert.</param>\n    /// <param name=\"TextEncoding\">The text encoding used to decode the converted bytes.</param>\n    /// <returns>Regular string that is equivalent to the input base-64 string.</returns>\n    /// <error>The length of Base64String, ignoring white-space characters, is not zero or a multiple of 4.</error>\n    /// <error>The format of Base64String is invalid. Base64String contains a non-base-64 character, more than two padding characters,\n    /// or a non-white space-character among the padding characters.</error>\n    procedure FromBase64(Base64String: Text; TextEncoding: TextEncoding): Text\n    begin\n        exit(Base64ConvertImpl.FromBase64(Base64String, TextEncoding));\n    end;\n\n    /// <summary>\n    /// Converts the specified string, which encodes binary data as base-64 digits, to an equivalent regular string.\n    /// </summary>\n    /// <param name=\"Base64String\">The string to convert.</param>\n    /// <param name=\"TextEncoding\">The text encoding used to decode the converted bytes.</param>\n    /// <param name=\"Codepage\">The Codepage if TextEncoding is MsDos or Windows.</param>\n    /// <returns>Regular string that is equivalent to the input base-64 string.</returns>\n    /// <error>The length of Base64String, ignoring white-space characters, is not zero or a multiple of 4.</error>\n    /// <error>The format of Base64String is invalid. Base64String contains a non-base-64 character, more than two padding characters,\n    /// or a non-white space-character among the padding characters.</error>\n    procedure FromBase64(Base64String: Text; TextEncoding: TextEncoding; Codepage: Integer): Text\n    begin\n        exit(Base64ConvertImpl.FromBase64(Base64String, TextEncoding, Codepage));\n    end;\n```\n### Add tests for the changed behavior\nRun the existing tests to check compatibility, and then add and run tests for the new behavior. The historical contribution included the following UTF16 tests in Base64ConvertTest.Codeunit.al. The file is now under `src\\System Application\\Test\\Base64 Convert\\src`.\nThe containing test codeunit supplies the Base64Convert and Assert variables, sample text, expected Base64 value, and error labels. Learn more in the Base64 Convert test source<https://github.com/microsoft/BCApps/blob/main/src/System%20Application/Test/Base64%20Convert/src/Base64ConvertTest.Codeunit.al>.\n```al\n    [Test]\n    procedure StringToBase64UTF16Test()\n    var\n        ConvertedText: Text;\n    begin\n        // [SCENARIO] A string variable is converted to base-64 string, binary representation is kept in UTF16\n\n        // [WHEN] The string is converted\n        ConvertedText := Base64Convert.ToBase64(SampleUTF16Txt, TextEncoding::UTF16);\n\n        // [THEN] The converted value is correct\n        Assert.AreEqual(Base64SampleUTF16Txt, ConvertedText, ConvertionToBase64UTF16Err);\n    end;\n\n    [Test]\n    procedure FromBase64UTF16StringTest()\n    var\n        ConvertedText: Text;\n    begin\n        // [SCENARIO] A base-64 string with UTF16 encoding is converted to a regular string\n\n        // [WHEN] The base-64 string is converted\n        ConvertedText := Base64Convert.FromBase64(Base64SampleUTF16Txt, TextEncoding::UTF16);\n\n        // [THEN] The converted value is correct\n        Assert.AreEqual(SampleUTF16Txt, ConvertedText, ConvertionFromBase64UTF16Err);\n    end;\n```\n## Submit your module changes\nBuild the changed app and its test app, and run the relevant tests before submitting your changes. Follow the BCApps local development guidelines for your environment.\n1. Run `git status` and review your changes.\n1. Stage each intended file with `git add \"<ChangedFile>\"`. Replace `<ChangedFile>` with its path.\n1. Commit your changes with `git commit -m \"<CommitMessage>\"`. Replace `<CommitMessage>` with a summary of the change.\n1. Push your branch with `git push --set-upstream origin \"<FeatureBranchName>\"`. The origin remote must point to your fork.\n1. Open a pull request from your branch to the BCApps repository. Select the appropriate target branch and link it to your approved issue by including `Fixes #<IssueNumber>` in the description.\nFollow the repository's contribution checks and review process. Complete the Contributor License Agreement steps if the pull request bot requests them.\n## Related information\nBCApps contribution guidelines<https://github.com/microsoft/BCApps/blob/main/CONTRIBUTING.md>\nBCApps local development environment guidelines<https://github.com/microsoft/BCApps/blob/main/LOCAL_DEV_ENV.md>\nModule architecture<devenv-blueprint>\nCreate a new module<devenv-new-module>"}