{"title":"Manage the identity of an AL app","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-app-identity/","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-app-identity, 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-app-identity","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 app IDs, versions, names, publishers, and tenant scopes identify AL apps and affect upgrades, dependencies, and data continuity.","date":"2026-10-09","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Manage the identity of an AL app","slug":"manage-the-identity-of-an-al-app","at":0,"chars":5717},{"level":2,"title":"When is it okay to change the ID of an app?","slug":"when-is-it-okay-to-change-the-id-of-an-app","at":2648,"chars":1464},{"level":2,"title":"When is it okay to change the name of an app?","slug":"when-is-it-okay-to-change-the-name-of-an-app","at":4112,"chars":420},{"level":2,"title":"When is it okay to change the publisher of an app?","slug":"when-is-it-okay-to-change-the-publisher-of-an-app","at":4532,"chars":433},{"level":2,"title":"When is it okay to change the version of an app?","slug":"when-is-it-okay-to-change-the-version-of-an-app","at":4965,"chars":515},{"level":2,"title":"Related information","slug":"related-information","at":5480,"chars":237}],"text":"# Manage the identity of an AL app\nApps built using AL extend the functionality of Business Central. The app.json and launch.json files are generated automatically when you create an AL project. The app.json file contains information about the app, including its publisher and the minimum version of the base application that it requires. The app.json file is often called the manifest. It contains many project settings, but only some settings define the identity of the app.\n> NOTE\n> With Business Central 2021 release wave 2, name and publisher are no longer considered part of the app identity and can therefore be changed to reflect branding or acquisition, for example. If you change either name or publisher, increment version. If you're using workspaces with multiple projects and change the name or publisher of an extension in the workspace, update the dependencies in the app.json file with the new name and publisher or you might encounter issues with reference resolution. See Working with multiple projects and project references<devenv-work-workspace-projects-references>.\n> IMPORTANT\n> In cases where the Application app is substituted with another application app, the name is still used as identification. See The Microsoft_Application.app File<devenv-application-app-file>.\nSetting|Example|Description\nid|`\"id\": \"00001111-aaaa-2222-bbbb-3333cccc4444\"`|The id, also known as the app ID. This GUID is generated automatically when the project is created. The app ID is also bound to how tables are named in Business Central and how the identity of an application is computed. Changing the app ID might have severe consequences, such as the app not functioning properly or data not being available.\nversion|`\"version\": \"1.0.0.0\"`|The version is used to distinguish between different iterations of your app. The version number should increase as you make changes to your app.\nFor more settings, see devenv-json-files.\nFor apps published in the Global scope, such as Marketplace and first-party apps, the app ID identifies the app across versions. The app ID and version identify a published app version. The generated `.app` package also has its own package ID. The Business Central service uses these identifiers in different flows. To prevent issues, the app ID must remain the same after an app is uploaded to the service, and the version must only increase. See https://learn.microsoft.com/powershell/module/microsoft.dynamics.nav.apps.management/publish-navapp.\nFor apps published in the Tenant scope, such as per-tenant extensions, the tenant ID is used together with the app ID and version to identify a published app version.\n## When is it okay to change the ID of an app?\nThe AL Language extension automatically generates the id of an app when you create a new app or use the AL: Generate manifest command.\nIf you have copied the app or the manifest from another app, you must change the id before publishing it to the online service as a per-tenant extension or Marketplace app.\nAfter the app has been published, you should only change the id if you intend to use the code base to develop a new app. You won't be able to upgrade from the app with the old id to the app with the new id because the system doesn't have knowledge about the correspondence.\nIf you have published your app as a per-tenant extension, but you're now considering publishing it to Marketplace, you must assign a new id to the Marketplace app, and ensure that it follows all the technical requirements for publishing to Marketplace. See Moving between extension scopes<devenv-extension-moving-scope>.\nIt's recommended to use a different id for the app that you publish from Visual Studio Code or to the container. Once you're satisfied with the quality of your app and ready to publish it to Marketplace, it's recommended to use a different id. If you don't follow this approach, the app that you have published from Visual Studio Code to a developer sandbox will be automatically unpublished if another user tries to install the Marketplace app. See Moving between extension scopes<devenv-extension-moving-scope>.\n## When is it okay to change the name of an app?\nIf you're targeting only Business Central 2021 release wave 2 or later, the name of an app can be changed at any point also after it has been published. If the name is changed, the version must be incremented as well.\nIf you're targeting versions of Business Central earlier than 2021 release wave 2, then the name of an app can't be changed after it has been published.\n## When is it okay to change the publisher of an app?\nIf you're targeting only Business Central 2021 release wave 2 or later, the publisher of an app can be changed at any point also after it's published. If the publisher is changed, the version must be incremented as well.\nIf you're targeting versions of Business Central earlier than 2021 release wave 2, then the publisher of an app can't be changed after it has been published.\n## When is it okay to change the version of an app?\nThe version must be incremented anytime a new version of your app is uploaded to Marketplace or as a per-tenant extension. While developing it in Visual Studio Code, you can keep using the same version and iterate on your code.\n> NOTE\n> In a Visual Studio Code workspace an app's name, publisher, and version are part of identifying a project and a project dependency. Therefore, if any of these properties change, it's recommended that you reload the workspace.\n## Related information\ndevenv-json-files\nhttps://learn.microsoft.com/powershell/module/microsoft.dynamics.nav.apps.management/publish-navapp\nWorking with multiple projects and project references<devenv-work-workspace-projects-references>"}