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

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 features flags required by the target runtime (e.g., NoImplicitWith from runtime 11.0+)