{"title":"Best practices for deprecation of AL code","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-deprecation-guidelines/","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-deprecation-guidelines, 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-deprecation-guidelines","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":"Description of best practices and guidelines for deprecating code in the Base App for Business Central.","date":"2024-04-30","meta":{"topic":"best-practice"},"outline":[{"level":1,"title":"Best practices for deprecation of AL code","slug":"best-practices-for-deprecation-of-al-code","at":0,"chars":4854},{"level":2,"title":"Obsoleting code","slug":"obsoleting-code","at":473,"chars":3333},{"level":2,"title":"Fixing code when objects are removed","slug":"fixing-code-when-objects-are-removed","at":3806,"chars":398},{"level":2,"title":"Obsoleting reports","slug":"obsoleting-reports","at":4204,"chars":245},{"level":2,"title":"Related information","slug":"related-information","at":4449,"chars":405}],"text":"# Best practices for deprecation of AL code\nThis article provides guidelines that describe how code in the Base App is obsoleted. It describes some best practices that Microsoft is using for obsoleting code, and is meant as a nonenforced guidance and best practice. You can use this article as an inspiration on how to set up a best practice for your own code. Learn more about how to obsolete code in Obsolete objects, methods, and symbols in AL<devenv-obsolete-objects>.\n## Obsoleting code\nWhen we obsolete code, we:\n Add the preprocessor statements `#if`, `#else`, and `#endif` surrounding the code to be obsoleted.\n Use one of the following preprocessor symbols, where the pattern is `CLEAN<Version>`, such as CLEAN15, CLEAN16, CLEAN17, and CLEAN18.\n> NOTE\n> These symbols aren't shipped with the product.\n For tables and fields, we also use CLEANSCHEMA in a second phase to delete the SQL schema.\n The version to use in the symbol matches the `<major>` of the ObsoleteTag. For example:\n   If a method is to be removed, then we use `#if not`\n    ```al\n    #if not CLEAN18\n        [Obsolete('Replaced by SetParameters().', '18.0')]\n        procedure SetParams(NewAnalysisArea: Option Sales,Purchase,Inventory; NewReportName: Code[10]; NewLineTemplateName: Code[10]; NewColumnTemplateName: Code[10])\n        begin\n            SetParameters(\"Analysis Area Type\".FromInteger(NewAnalysisArea), NewReportName, NewLineTemplateName, NewColumnTemplateName);\n        end;\n    #endif\n    ```\n   If an action is to be removed, then we also use `#if not`\n    ```al\n\n    #if not CLEAN17\n        action(\"Social Listening Setup\")\n        {\n            ApplicationArea = All;\n            Caption = 'Social Engagement Setup';\n            RunObject = page \"Social Listening Setup\";\n            Visible = false;\n            ObsoleteState = Pending;\n            ObsoleteReason = 'Microsoft Social Engagement has been discontinued.';\n            ObsoleteTag = '17.0';\n        }\n    #endif\n    ```\n   If a table or table field is to be removed, then we use `#if #else #endif`\n    ```al\n\n    #if not CLEANSCHEMA19\n    table 1808 \"Aggregated Assisted Setup\"\n    {\n        Access = Internal;\n        Caption = 'Aggregated Assisted Setup';\n    #if CLEAN16\n        ObsoleteState = Removed;\n        ObsoleteTag = '19.0';\n    #else\n        ObsoleteState = Pending;\n        ObsoleteTag = '16.0';\n    #endif\n        ObsoleteReason = 'Data available in Assisted Setup already- extensions also register in the same table.';\n    }\n    #endif\n\n    ```\n    ```al\n    #if not CLEANSCHEMA20\n    field(11701; \"Bank Account No.\"; Text[30])\n    {\n        Caption = 'Bank Account No.';\n        Editable = false;\n    #if CLEAN17\n        ObsoleteState = Removed;\n        ObsoleteTag = '20.0';\n    #else\n        ObsoleteState = Pending;\n        ObsoleteTag = '17.0';\n    #endif\n        ObsoleteReason = 'Moved to Core Localization Pack for Czech.';\n    }\n    #endif\n    ```\n   If a table is to be marked as Temporary, then we use `#if #else #endif`\n    ```al\n\n    table 5503 \"Acc. Schedule Line Entity\"\n    {\n        Caption = 'Acc. Schedule Line Entity';\n        // TableType = Temporary;\n    #if CLEAN17\n        TableType = Temporary;\n    #else\n        ObsoleteState = Pending;\n        ObsoleteReason = 'Table will be marked as TableType=Temporary. Make sure you are not using this table to store records';\n        ObsoleteTag = '17.0';\n    #endif\n    ```\nTo have the compiler take the new 'clean' code path, symbols must be defined. The symbols are defined in the app.json file with the following setting. See devenv-json-files.\n```al\n\"preprocessorSymbols\": [ \"CLEAN15\", \"CLEAN16\", \"CLEAN17\", \"CLEAN18\" ]\n```\n> IMPORTANT\n> A best practice is to change this locally to make sure everything compiles, run tests locally, and then submit test jobs.\n## Fixing code when objects are removed\nIf an action or other code element points to a now removed object, then the guidance is to:\n Ensure that the action is obsoleted.\n Add preprocessor statements to fix the issue.\n   If code points to an obsoleted method, then use directives to put in the fixed code.\n   If code points to an obsoleted table/field, then use directives to put in the fixed code.\n## Obsoleting reports\nIf you plan to deprecate reports in your Marketplace apps or per-tenant extensions, you might want to inform other developers and your users before you remove the reports. See Obsoleting reports<devenv-reports-obsoletion>.\n## Related information\nObsoleting reports<devenv-reports-obsoletion>\nAL development environment<devenv-reference-overview>\ndirectives/devenv-directives-in-al\nMicrosoft timeline for deprecating code in Business Central<devenv-deprecation-timeline>\nproperties/devenv-obsoletetag-property\nproperties/devenv-obsoletestate-property\nproperties/devenv-obsoletereason-property\nattributes/devenv-obsolete-attribute"}