Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 14:46:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

knowledge: improve review precision from BCApps PR 10252 feedback

Browse source
This commit is contained in:
github-actions[bot] 2026-09-09 10:35:51 +00:00
parent 8584217c75
commit e7ee9b4b5a
1 changed files with 5 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

6
microsoft/knowledge/upgrade/use-upgrade-tags-not-version-checks.md
View file

@ -1,7 +1,7 @@
--- ---
bc-version: [all] bc-version: [all]
domain: upgrade domain: upgrade
keywords: [upgrade-tag, version-check, dataversion, has-upgrade-tag, set-upgrade-tag, control-flow] keywords: [upgrade-tag, version-check, dataversion, has-upgrade-tag, set-upgrade-tag, control-flow, dynamic-check, runtime-function, always-log-table, non-persisted-state]
technologies: [al] technologies: [al]
countries: [w1] countries: [w1]
application-area: [all] application-area: [all]
@ -13,6 +13,10 @@ application-area: [all]
Each piece of upgrade logic must run exactly once per company (or database) across the lifetime of an extension. The platform mechanism for that is the `Upgrade Tag` codeunit: a procedure asks `HasUpgradeTag(MyTag())` at entry, performs its work, then calls `SetUpgradeTag(MyTag())` to record completion. Subsequent upgrades on the same tenant see the tag and skip the work. Hand-rolled `if MyApp.DataVersion().Major < N then ...` chains are the wrong tool: they are version-coupled, accumulate stale branches over time, and break when a tenant skips a version. Each piece of upgrade logic must run exactly once per company (or database) across the lifetime of an extension. The platform mechanism for that is the `Upgrade Tag` codeunit: a procedure asks `HasUpgradeTag(MyTag())` at entry, performs its work, then calls `SetUpgradeTag(MyTag())` to record completion. Subsequent upgrades on the same tenant see the tag and skip the work. Hand-rolled `if MyApp.DataVersion().Major < N then ...` chains are the wrong tool: they are version-coupled, accumulate stale branches over time, and break when a tenant skips a version.
## Scope
Upgrade tags guard one-time work that mutates persisted, per-company state (data, setup records, or a stored schema baseline) so it runs exactly once. They do not apply to a hard-coded list or condition inside an ordinary runtime function that is evaluated fresh on every call and never persists its result — for example, a function that decides live whether a given table is in the "always log changes" set for the change-log feature. Adding or removing an entry from such a list is a normal behavior change: it only affects future evaluations of the function, there is no stored per-company flag or record whose absence would leave old data stranded, so no upgrade tag, upgrade codeunit, or migration step is needed.
## Best Practice ## Best Practice
Every upgrade procedure starts with a `HasUpgradeTag` guard and ends with `SetUpgradeTag` once the work is committed. Each feature gets its own tag string so features can be re-run independently if needed. Every upgrade procedure starts with a `HasUpgradeTag` guard and ends with `SetUpgradeTag` once the work is committed. Each feature gets its own tag string so features can be re-run independently if needed.