skill-migrate
AL version migration for Business Central. Use when upgrading extensions between BC versions, handling breaking changes, or implementing rollback strategies.
javiarmesto · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add javiarmesto/ALDC-AL-Development-Collection --skill skill-migrate技能说明
name: skill-migrate description: AL version migration for Business Central. Use when upgrading extensions between BC versions, handling breaking changes, or implementing rollback strategies.
Skill: AL Project Migration
Purpose
Plan and execute BC platform version upgrades: app.json configuration, breaking-change remediation, deprecated API replacement, event signature updates, upgrade codeunits for data migration, rollback strategy, and manifest regeneration.
When to Load
This skill should be loaded when:
- Upgrading an AL extension to a newer BC platform version (e.g., BC 23.x → 24.x)
- Fixing compilation errors after updating the runtime or platform property
- Replacing deprecated AL patterns (C/AL legacy, obsolete APIs)
- Updating event subscriber signatures after base-app changes
- Writing upgrade codeunits for schema changes or data migration
- Generating a full deployment package after migration
Core Patterns
For BC29 / AL18, first read AL18 capability checks when selecting new manifest, public-resource, isolation, testing or translation features. Apply only the sections needed by the requirement; distinguish announced capabilities from locally verified declarations. Keep BC28 configuration unchanged unless an upgrade is part of the approved task.
Pattern 1: App.json Platform Update
Update the three version-sensitive properties in app.json:
{
"platform": "25.0.0.0",
"runtime": "14.0",
"application": "25.0.0.0",
"dependencies": [
{
"id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
"name": "System Application",
"publisher": "Microsoft",
"version": "25.0.0.0"
}
],
"features": ["TranslationFile", "GenerateCaptions", "NoImplicitWith"]
}
Rules:
platform— target BC platform version (major.minor.0.0)runtime— AL runtime version matching the target (see runtime matrix)application— must match or be compatible with target platform- Resolve each dependency by identity, minimum version, target runtime and required APIs; do not require every library version to numerically match the application version.
- Add new
featuresflags required by the target runtime (e.g.,NoImplicitWithfrom runtime 11.0+)
Pattern 2: Deprecated Code Replacement
Replace legacy patterns with modern equivalents:
// ❌ Deprecated — C/AL style
Record.FIND('-');
Record.FINDSET(TRUE, TRUE);
IF Record.FINDFIRST THEN;
Record.INIT;
Record.INSERT;
// ✅ Modern — AL patterns
Record.FindSet();
Record.FindSet(true, true);
if Record.FindFirst() then;
Record.Init();
Record.Insert(true);
// ❌ Deprecated — WITH statement (removed in NoImplicitWith)
with SalesHeader do begin
"Document Type" := "Document Type"::Order;
"Sell-to Customer No." := CustomerNo;
Insert(true);
end;
// ✅ Modern — explicit record reference
SalesHeader."Document Type" := SalesHeader."Document Type"::Order;
SalesHeader."Sell-to Customer No." := CustomerNo;
SalesHeader.Insert(true);
// ❌ Deprecated — TextConst (runtime < 6.0)
CustomerNotFoundErr@1000 : TextConst 'ENU=Customer %1 not found.';
// ✅ Modern — Label
var
CustomerNotFoundErr: Label 'Customer %1 not found.';
Pattern 3: Event Signature Migration
When base-app events add or change parameters between versions:
// BC 23.x subscriber — 3 parameters
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post",
OnBeforePostSalesDoc, '', false, false)]
local procedure OnBeforePost(
var SalesHeader: Record "Sales Header";
CommitIsSuppressed: Boolean;
var IsHandled: Boolean)
begin
// ...
end;
// BC 24.x — same event now has 4 parameters (new PreviewMode added)
[EventSubscriber(ObjectType::Codeunit, Codeunit::"Sales-Post",
OnBeforePostSalesDoc, '', false, false)]
local procedure OnBeforePost(
var SalesHeader: Record "Sales Header";
CommitIsSuppressed: Boolean;
PreviewMode: Boolean;
var IsHandled: Boolean)
begin
// ...
end;
Migration steps:
- Build with
al_build— signature mismatches produceAL0482errors - Use
al_get_object_definitionto inspect the new publisher signature - Update parameter list to match exactly (name, type, order)
- Re-verify with
al_build
Pattern 4: Obsolete Object Handling
Handle objects marked ObsoleteState = Removed in the target version:
// Step 1: Find usage of removed objects
// al_search_objects — search for the obsolete table/page/codeunit
// Step 2: Replace with the designated successor
// Before (removed in BC 24):
// Codeunit 80 "Sales-Post (Yes/No)" — ObsoleteState = Removed
// After:
Codeunit.Run(Codeunit::"Sales-Post", SalesHeader);
// Step 3: Check ObsoleteReason for migration guidance
// ObsoleteReason typically says: "Use codeunit X instead"
Process:
- Compile → collect all
AL0503(removed) andAL0432(pending) warnings - For
Removed— must fix before compilation succeeds - For
Pending— fix proactively to avoid future breaks - Check release notes for each removed object's replacement
Pattern 5: Upgrade Codeunit (Data Migration)
Use upgrade codeunits to transform data when schema changes between versions:
codeunit 50100 "Contoso Data Upgrade"
{
Subtype = Upgrade;
trigger OnUpgradePerCompany()
var
Module: Info;
begin
Module.DataVersion(1); // check data version tracking
MigrateCustomerLoyaltyData();
SplitAddressFields();
end;
trigger OnValidateUpgradePerCompany()
begin
// Pre-upgrade validation — runs before OnUpgradePerCompany
VerifyDataIntegrity();
end;
local procedure MigrateCustomerLoyaltyData()
var
Customer: Record Customer;
ContosoLoyalty: Record "Contoso Loyalty Entry";
UpgradeTag: Codeunit "Upgrad
阅读完整来源 ↗