Advpl To Tlpp Migration

AdvPL-to-TLPP Migration

Overview

Migrate legacy AdvPL source files (.prw, .prx) to modern TLPP (.tlpp) incrementally and safely. TLPP is an evolution of AdvPL that introduces modern language features while maintaining full backward compatibility with existing AdvPL constructs. This skill provides a structured migration path that can be applied gradually — no forced rewrite is required.

When to Use

Use this skill when:

• Modernizing legacy AdvPL code to TLPP
• Converting .prw files to .tlpp
• Adopting TLPP-exclusive features (typing, try-catch, namespace, etc.)
• Replacing prohibited constructs (e.g., StaticCall) in TLPP sources
• Preparing code for TLPP REST migration from WsRESTful
• Onboarding developers transitioning from AdvPL to TLPP

---

Feature Comparison: AdvPL vs. TLPP

For the complete feature-by-feature comparison table (19 features covering scoping, control structures, typing, namespaces, Try-Catch, JSON inline, class modifiers, REST, and StaticCall status), see [advpl-tlpp-feature-comparison.md](references/advpl-tlpp-feature-comparison.md).

---

Migration Process

> MANDATORY RULE — File Extension: Any source file that includes #include "tlpp-core.th" or uses TLPP-exclusive features must use the .tlpp extension. If a .prw or .prx file is being migrated or modified to adopt TLPP constructs, rename it to .tlpp as part of the same change. The AdvPL compiler silently ignores TLPP directives in .prw/.prx files, which leads to hard-to-diagnose failures. Always change the extension first.

The migration involves 15 steps, each addressing a specific AdvPL → TLPP transformation:

1. File Extension and Includes — .prw → .tlpp, add #include "tlpp-core.th"
2. Add Namespace — Organize code with Namespace company.module.feature
3. Add Type Annotations — Variables, parameters, return values (as Type)
4. Replace ErrorBlock with Try-Catch — Modern exception handling
5. Replace StaticCall — Use FWLoadMenuDef, FWLoadModel, namespace calls
6. Use Long Identifier Names — TLPP removes the 10-char limit
7. Use Named Parameters — Improve readability at call sites
8. Use JSON Inline — Replace JsonObject():New() chains
9. Add Class Access Modifiers — Private, Protected, Public
10. Migrate WsRESTful to TLPP REST — Annotation-based @Get, @Post, etc.
11. Fix Incorrect Inheritance — LongNameClass (not LongClassName)
12. Remove ISAM Driver Usage — Migrate to FWTemporaryTable
13. Migrate Console APIs to FWLogMsg — Replace ConOut, OutErr, ?
14. Remove IIF Usage — Replace with If/Else/EndIf
15. Migrate FormCommit Override to FWModelEvent — Use FWFormCommit(oModel)

For complete before/after diff examples for all 15 steps, see [tlpp-migration-patterns.md](references/tlpp-migration-patterns.md).

---

Migration Checklist

Pre-Migration

• [ ] Source file is under version control with a clean commit
• [ ] Existing tests pass (or tests exist for the code)
• [ ] Dependencies on the file are identified (callers, includes)
• [ ] Team is aware of the migration (naming changes affect callers)

File Transformation

• [ ] File extension changed from .prw to .tlpp
• [ ] #include "tlpp-core.th" added as the first include
• [ ] Namespace declaration added
• [ ] All StaticCall() replaced with direct calls or FWLoad* functions
• [ ] User Function return types added (as Type)
• [ ] Parameter types added (as Type)
• [ ] Variable types added (as Type)

Modernization (Incremental)

• [ ] ErrorBlock patterns replaced with Try-Catch where appropriate
• [ ] Short identifier names expanded to descriptive names
• [ ] Private variable scope replaced with Local where possible
• [ ] Class access modifiers added (Private, Protected, Public)
• [ ] Named parameters used for functions with 3+ parameters
• [ ] JSON inline syntax used for JSON object construction
• [ ] WsRESTful services migrated to TLPP REST annotations
• [ ] LongNameClass used for inheritance (not LongClassName)
• [ ] ISAM drivers (MSCREATE, DBCREATE, CRIATRAB) replaced with FWTemporaryTable
• [ ] ConOut() / OutErr() / ? replaced with FWLogMsg()
• [ ] IIF() replaced with If/Else/EndIf blocks
• [ ] FormCommit overrides migrated to FWModelEvent / FWFormCommit(oModel) pattern

> Refer to [references/sonarqube-rules-reference.md](../references/sonarqube-rules-reference.md) for the complete SonarQube rules reference.

Post-Migration

• [ ] Source compiles without errors
• [ ] All unit/integration tests pass
• [ ] Callers updated if function signatures changed
• [ ] RPO recompiled and tested in development environment
• [ ] No regression in existing functionality

---

Common Migration Pitfalls

| Pitfall | Symptom | Resolution | | ------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ | | Using #include "tlpp-core.th" in a .prw/.prx file | TLPP features silently ignored; unexpected runtime behavior | Rename the file to .tlpp before adding TLPP includes or features | | Using long identifiers in .prw files | Silent truncation, wrong function calls | Only use long names in .tlpp files | | StaticCall in .tlpp file | Compilation error | Replace with FWLoadMenuDef, FWLoadModel, or namespace call | | Missing #include "tlpp-core.th" | TLPP features not recognized | Add as the first include | | Default access modifier changed | Class members inaccessible from outside | Explicitly add Public to members that need external access | | Try-Catch around non-TLPP calls | ErrorBlock still needed for pure AdvPL error flows | Use Try-Catch regardless — it captures AdvPL throws too | | JSON inline without line continuations | Compilation error | Use ; at end of each line in JSON inline blocks | | Access modifiers or static in method implementation | Compilation error or unexpected behavior | Method implementations use bare method — NEVER public method, static method, etc. Modifiers are ONLY in the class declaration |

---

Incremental Migration Strategy

Migration does not need to be all-or-nothing. Follow this priority order:

1. Mandatory for TLPP: File extension + tlpp-core.th include + remove StaticCall
2. High value: Add Namespace + type annotations (catches bugs at compile time)
3. Medium value: Replace ErrorBlock with Try-Catch, add class access modifiers, fix LongNameClass inheritance
4. SonarQube compliance: Remove IIF, ConOut → FWLogMsg, ISAM → FWTemporaryTable, FormCommit → FWModelEvent
5. Nice to have: Long identifiers, named parameters, JSON inline

> AdvPL and TLPP coexist. A .tlpp file can call AdvPL functions and vice versa. You don't need to migrate everything at once.

---

Troubleshooting

• StaticCall not compiling in TLPP: StaticCall is prohibited in TLPP. Replace StaticCall(TClass, Method, params) with TClass():Method(params).
• Include conflicts after renaming to .tlpp: Replace #include "protheus.ch" with #include "tlpp-core.th". Add #include "totvs.ch" if the source uses Protheus framework functions. Do not keep protheus.ch — use totvs.ch instead.
• Namespace resolution errors: Ensure the Namespace declaration matches the directory structure and that callers use the fully qualified name or a Using directive.
• Functions not found after migration: AdvPL and TLPP can coexist. If a .tlpp file calls an AdvPL function, the AdvPL source must still be compiled in the RPO.
• Type mismatch at compile time: TLPP type annotations are strict. Ensure parameter types and return types match exactly — implicit conversions allowed in AdvPL may fail in TLPP.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: totvs
• Source: totvs/engpro-advpl-tlpp-skills
• License: MIT

Install and usage instructions live in the source repository linked above.