Code Conversion from C/AL to AL

Article
05/01/2023

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

This article explains how to convert a Business Central (version 14) C/AL code-customized on-premises solution to AL code.

You'll use this procedure as part of the upgrade process when going from version 14 to a later version, from 18 to 20.

Before you start

Get familiar with the basics of setting up and developing in Visual Studio Code and AL, see Developing Extensions in AL.

Note

Moving on-premise C/AL code customizations to Dynamics 365 Business Central online, requires converting these to AL extensions. This could include converting the C/AL deltas to AL extension code as a starting point, as outlined in The Txt2Al Conversion Tool.

Also, review the Known Issues for information about issues that may affect the upgrade.

Breaking changes

When converting from C/AL to AL, it's important that you don't introduce any breaking schema changes to the database. Otherwise, you won't be able to synchronize the new extension with the database.

Task 1: Import the test library into your C/AL solution

If your solution uses Microsoft (1st-party) extensions, you'll have to convert the test library from C/AL to AL. The reason for this is that the Microsoft extensions rely on the test symbols. The easiest way is to import the CALTestLibraries.W1.fob file into the old database. This file is available on the version 14 installation media (DVD) in the TestToolKit folder.

You can do this using the (Dynamics NAV Development Environment). For more information, see Exporting and Importing Objects.

Task 2: Compile all the objects in your C/AL solution

Compiling all the objects is a prerequisite for a successful and complete export. To compile objects, you can use either of the following tools:

C/SIDE (Dynamics NAV Development Environment). See Compiling Objects.
Compile-NAVApplicationObject cmdlet of the Dynamics NAV Development Shell. Make sure to run this cmdlet as an administrator.

Task 3: Export the application objects to the new TXT syntax

Once the application compiles, you must export all C/AL application objects, except system tables and codeunits (IDs in the 2000000000 range), to the new TXT format. The exported objects will be used as input to the Txt2AL conversion tool. To export objects, use the Export-NAVApplicationObject cmdlet of the Dynamics NAV Development Shell. it's important to:

Omit all system objects, which have IDs in the 2000000000 range.
Use the ExportToNewSyntax switch to export the objects in a syntax that is compatible with the Txt2Al conversion tool.

The Export-NAVApplicationObject cmdlet will export all objects to a single .txt file. If you imported the test library objects into the database, then you'll export the base application objects and the test library separately. Later, you'll create a separate AL project for each set of files.

For example, do the following steps:

Export the custom base application objects.

Create a folder for storing the exported base application objects to TXT files (for example, c:\export2al\baseapplication).

Run the following commands to export tha application objects, but omitting the system objects and test library objects.

Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "c:\export2al\baseapplication\exportedbc14app-part1.txt" -Filter 'Id=1..129999'

Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "c:\export2al\baseapplication\exportedbc14app-part2.txt" -Filter 'Id=140000..1999999999'

Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "c:\export2al\baseapplication\exportedbc14testobjects.txt" -Filter 'Id=130400..130416'

Export the test library objects.

Create a folder for storing the exported test library objects to TXT files (for example, c:\export2al\testlibrary).

Run the following commands to export the test library objects only

Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "c:\export2al\testlibrary\bc14testlibrary-part1.txt" -Filter 'Id=130000..130399'

Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "c:\export2al\testlibrary\bc14testlibrary-part2.txt" -Filter 'Id=130440..139999'

Task 4: Create a declaration file for custom .NET assemblies (optional)

If your solution contains .NET interoperability code and control add-ins, you can create a file that contains the declarations to the assemblies. This file will be used when you convert the C/AL TXT files to AL in the next step. Alternatively, after the conversion, you'll have to manually add the declarations to objects that use the assemblies.

To create the file, use a text editor or Visual Studio code to create a file that contains the assembly declarations as follows:

dotnet 

{ 
    assembly("Microsoft.Dynamics.Nav.Client.BusinessChart") 
    { 
        type("Microsoft.Dynamics.Nav.Client.BusinessChart.BusinessChartAddIn";"Microsoft.Dynamics.Nav.Client.BusinessChart") 
        { 
            IsControlAddIn = true; 
        } 

        // Other control add-ins in this assembly 
    } 

    // Other assemblies containing control add ins 
}

Save the file with any name and the extension .al, for example mydotnet.al. Make a note of the path because you'll use it in the next step.

Task 5: Convert the C/AL TXT files to AL

With C/AL exported to the new TXT format, you now convert the code to AL using the The Txt2Al Conversion Tool. The Txt2Al creates .al files for each object in the TXT files. Similar to Task 3, if you imported the test library objects into the database, then you'll convert the base application objects and the test library separately.

Get the Txt2AL conversion tool

The Txt2Al conversion tool (txt2al.exe) is only available with version 14, which is the last version to support C/AL. Use this version of the tool no matter what later version you may eventually be upgrading to. The AL objects created by the tool will be compatible with later versions.

You find the txt2al.exe on the installation media (DVD) in the "DVD\RoleTailoredClient\program files\Microsoft Dynamics NAV\140\RoleTailored Client" folder. Or, it's installed locally with Dynamics NAV Development Environment, for example, in the "C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client" folder.

Run the Txt2AL conversion tool

Convert the base application TXT files to AL.
1. Create a folder for storing the AL files for base application objects (for example, c:\export2al\baseapplication\al).
2. Start a command prompt as administrator, and navigate to the folder that contain txt2al.exe file.
  
  By default, the location is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client.
3. Run the txt2al command:
```
txt2al --source=C:\export2al\baseapplication --target=C:\export2al\baseapplication\al --injectDotNetAddIns --dotNetAddInsPackage=C:\export2al\dotnet\mydotnet.al --dotNetTypePrefix=BC --rename
```
  If your solution contains .NET interoperability code, the following Txt2Al command line parameters are used to achieve a conversion that requires less manual intervention:
  - --injectDotNetAddIns injects the definition of standard .NET add-ins in the resulting .NET package. The standard .NET add-ins are a set of add-ins that are embedded into the platform.
  - --dotNetAddInsPackage should be used to point the conversion tool to an AL file containing declarations for the .NET types that represent .NET control addins. Use this to inject a custom set of .NET control add-in declarations. This parameter is only required if you completed Task 4, and you set it to point to the location of the dotnet.al file.
    
    Note
    
    If you are interested in migrating your localization resources, you should use the --addLegacyTranslationInfo switch to instruct Txt2Al to generate information about the legacy IDs of the translation code.
  - --dotNetTypePrefix specifies a prefix to be used for all .NET type aliases created during the conversion. This will ensure that no naming conflicts occur with existing types. In the example, BC is the prefix.
  - --rename renames the output files to prevent clashes with the source .txt files.
  When completed, there will be an .al file for each object.
Convert the test library TXT files to AL.

This is similar to the previous step.
1. Create a folder for storing the AL files for test objects (for example, c:\export2al\testlibrary\al).
2. Run the txt2al command:
```
txt2al --source=C:\export2al\testlibrary --target=C:\export2al\testlibrary\al --injectDotNetAddIns --dotNetTypePrefix=BCTest --rename
```
  Use a different value for the --dotNetTypePrefix than you did for the base application.

Task 6: Create a new application database for development

To build your base application, you'll create a new application database on the Business Central platform version that you're upgrading to (like 18, 19, or 20). This will only be used during development.

Start the Business Central Administration Shell for new version as an administrator.

Run the New-NAVApplicationDatabase cmdlet to create the database. For example:

New-NAVApplicationDatabase -DatabaseServer .\BCDEMO -DatabaseName MyDBforupgrade

Connect your Business Central Server instance to the database. See Connecting a Business Central Server Instance to a Database.
```
Set-NAVServerConfiguration -ServerInstance BC -KeyName DatabaseName -KeyValue "MyDBforupgrade"
```

Restart the server instance.

Restart-NAVServerInstance -ServerInstance BC

Task 7: Create and build an AL project for custom base application

In this task, you'll create an AL project in Visual Studio code that you'll use for building your custom base application extension based on your converted C/AL application.

If you haven't already, install Visual Studio Code and the latest AL Language extension for version 18, 19, or 20 as outlined in Get Started with AL.
Configure Visual Studio Code for optimal performance with AL projects.

This step is optional, but recommended. For more information, see Optimize Visual Studio Code for Editing and Building.
In Visual Studio Code, from the Command Palette, select the AL Go! command to create a new project.

Specify the path for the project, and set the Target Platform to version you're upgrading to. When prompted to select your server, choose Your own server.
Create a .alpackages folder in the root folder of the project and then copy the system (platform) symbols extension (System.app file) to the folder.

The System.app file is located where you installed the AL Development Environment, which by default is the C:\Program Files (x86)\Microsoft Dynamics 365 Business Central<180, 190, 200>\AL Development Environment folder. This package contains the symbols for all the system tables and codeunits.
Delete the HelloWorld.al sample file from the project.
Modify the settings.json file of Visual Studio Code to configure the assembly probing path.

Change "al.assemblyProbingPaths": ["./.netpackages"] to point to all the folders that contain .NET assemblies that are used by your project. Here is an example that contains the most typical paths:
```
"al.assemblyProbingPaths": [
"C:\\Program Files\\Microsoft Dynamics 365 Business Central\\200\\Service",
"C:\\Program Files (x86)\\Microsoft Dynamics 365 Business Central\\200\\RoleTailored Client",
"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.8",
"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\WindowsPowerShell"
]
```
Replace 200 with the value that matches your installation, like 180 or 190.

For more information about the settings.json, see User and Workspace Settings.

Note

Adding assemblies to the folders in your assembly probing paths is not automatically detected by the compiler. You must restart Visual Studio Code for the changes to be detected.

Modify the app.json for the project as follows:

Parameter	Value
`"id":`	Use the default that was created for you.
`"name":`	Specify any valid name.
`"publisher":`	Specify any valid publisher name.
`"version":`	You can use any valid version number, but it's recommended to set it to the same version as the C/AL application.
`"dependencies":`	Delete all values, so this parameter is empty.
`"platform":`	Set to match the platform version that you're upgrading to: `"20.0.0.0"`- version 20 `"19.0.0.0"`- version 19 `"18.0.0.0"`- version 18
`"application":`	Remove this parameter.
`"idRange":`	Set to include all the IDs used by your base application, or leave it blank.
`"runtime":`	Set to match the version that you're upgrading to: `"9.0"`- version 20 `"8.0"`- version 19 `"7.0"`- version 18
`"target":"`	Add this parameter and set to `"OnPrem"`.

For example:

{
    "id": "11111111-aaaa-2222-bbbb-333333333333",
    "name": "My Base Application",
    "publisher": "Microsoft",
    "version": "14.13.0.0",
    "brief": "",
    "description": "",
    "privacyStatement": "",
    "EULA": "",
    "help": "",
    "url": "",
    "logo": "",
    "dependencies": [],
    "screenshots": [],
    "platform": "19.0.0.0",
    "idRanges": [  ],
    "contextSensitiveHelpUrl": "https://BC14cal-to-18al-app.com/help/",
    "showMyCode": true,
    "runtime": "8.0",
    "target":  "OnPrem"
}

Copy all of the base application AL files generated in the previous task (Task 5) to the root folder of your project.
Open the dotnet.al file for the project, and make the following changes:
- Delete all instances of Version = '14.0.0.0'; for Microsoft.Dynamics.Nav assembly declarations.
- For the DocumentFormat.OpenXml assembly declaration, remove the version and culture keys and set PublicKeyToken = '8fb06cb64d019a17'.
```
assembly("DocumentFormat.OpenXml")
{
    PublicKeyToken = '8fb06cb64d019a17';
    ...
```
Delete objects that are related to the client debugger client.

Debugging from the client has been discontinued, and replaced by AL Debugger. The version 14 debugger objects aren't supported on later versions. To avoid compilation errors, delete the following objects:
- Debugger.Page.al
- DebuggerBreakpointCondition.Page.al
- DebuggerBreakpointList.Page.al
- DebuggerCallstackFactBox.Page.al
- DebuggerCodeViewer.Page.al
- DebuggerManagement.Codeunit.al
- DebuggerVariableList.Page.al
- DebuggerWatchValueFactBox.Page.al
- SessionList.Page.al
You might also have to remove references to SessionList in ChangeGlobalDimensions.Codeunit.al.

Build and compile your project (select Ctrl+Shift+B).

The AL compiler will issue errors for constructs that aren't valid. Fix any errors that occur, and build again.

Tip

If you are maintaining your C/AL solution going forward, we recommend that you fix errors in C/AL objects and convert to AL again. This makes it future changes easier to forward push changes because code bases will be similar.

When all errors are fixed, the custom base application package (.app) will be created.

Task 8: Create and build an AL project for the test library

If you converted the test library form C/AL to AL, you'll now create and build a project for test library, similar to what you did for the base application.

Follow steps 1 through 5 in Task 7 to create an AL project for the test library.

As with base application project, you have to modify the app.json file, but in this case, you have to change the version and add a dependency on the base application that you created.

Parameter	Value
`"id":`	Use the default that was created for you.
`"name":`	Specify any valid name.
`"publisher":`	Specify any valid publisher name.
`"version":`	You can use any valid version number, but it's recommended to set it to the same version as the C/AL application.
`"dependencies":`	Set this include information that matches the custom the base application you created in the previous task.
`"platform":`	Set to match the platform version that you're upgrading to: `"20.0.0.0"`- version 20 `"19.0.0.0"`- version 19 `"18.0.0.0"`- version 18
`"application":`	Remove this parameter.
`"idRange":`	Set to include all the IDs used by your test application, or leave it blank.
`"runtime":`	Set to match the version that you're upgrading to: `"9.0"`- version 20 `"8.0"`- version 19 `"7.0"`- version 18
`"target":"`	Add this parameter and set to `"OnPrem"`.