skill-migrate

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

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
• Update all dependencies versions to match the target release
• Add new features flags required by the target runtime (e.g., NoImplicitWith from 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);