Code Conversion from C/AL to AL

Important

Please note that this topic is a draft in progress. We are still working on adding more details to the steps described in this topic.

This article explains how to convert your existing C/AL code-customized on-premises solution to an AL code-customized on-premises solution.

Before you start, we recommend getting 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.

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

If your solution uses Microsoft (1st-party) extensions, you will 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 to do this 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:

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 used as input to the Txt2AL conversion tool. To export objects, use the Export-NAVApplicationObject cmdlet of the Dynamics NAV Development Shell. It is important to:

  • Omit 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 will export the base application objects and the test library separately because later, you will create a separate AL project for each set of files.

For example, do the following:

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

    2. 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'
      
  2. Export the test library objects.
    1. Create a folder for storing the exported test library objects to TXT files (for example, c:\export2al\testlibrary).

    2. 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 will 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 will 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 will convert the base application objects and the test library separately.

  1. 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
      

      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.

      When completed, there will be an .al file for for each object.

  2. 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 base application objects (for example, c:\export2al\baseapplication\al).

    2. Run the txt2al command:

      txt2al --source=C:\export2al\testlibrary --target=C:\export2al\testlibrary\al --injectDotNetAddIns --dotNetTypePrefix=BCTest
      

      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 will create a new application database on the Business Central version 15 platform. This will only be used during development.

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

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

    New-NAVApplicationDatabase -DatabaseServer .\BCDEMO -DatabaseName MyDBforupgrade
    
  3. Connect your Business Central Server instance to the database. See Connecting a Business Central Server Instance to a Database.

    Set-NAVServerConfiguration -ServerInstance BC150 -KeyName DatabaseName -KeyValue "MyDBforupgrade"
    
  4. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance BC150
    

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

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

  1. If you haven't already, install Visual Studio Code and the latest AL Language extension for version 15.0 as outlined in Getting Started with AL.

  2. 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.

  3. 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 4.0 Business Central 2019 release wave 2. When prompted to select your server, choose Your own server.

  4. 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\150\AL Development Environment folder. This package contains the symbols for all the system tables and codeunits.

  5. Delete the HelloWorld.al sample file from the project.

  6. 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\\150",
    "C:\\Program Files (x86)\\Microsoft Dynamics 365 Business Central\\150\\RoleTailored Client",
    "C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.7.2",
    "C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\WindowsPowerShell\\3.0"
    ]
    

    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.

  7. Modify the app.json for the project as follows:

    • Important The ID, name, and publisher, and version of the custom base application must match the Business Central base application. Set the parameters to the following values`:

        "appId": "437dbf0e-84ff-417a-965d-ed2bb9650972",
        "name": "Base Application",
        "publisher": "Microsoft",
        "version": "14.5.0.0"
      

      We recommend that you set the "version" to the same version as the C/AL application.

    • Set the target to OnPrem.

    • Change the idRange to include all the IDs used by your base application (or leave blank).

    • Delete the values in the dependencies parameter.

  8. Copy all of the base application AL files generated in the previous task (Task 5) to the root folder of your project.

  9. 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';
          ...
      
  10. 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 are not supported on version 15. 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.

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

    The AL compiler will issue errors for constructs that are not 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 foward 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 will now create and build a project for test library, similar to what you did for the base application.

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

    2. 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.

      • Set the "version" to the old application version, such as 14.5.0.0.

      • Set the "dependencies" to include information about your custom the base application.

        "dependencies": [
        {
            "appId": "437dbf0e-84ff-417a-965d-ed2bb9650972",
            "publisher": "Microsoft",
            "name": "Base Application",
            "version": "14.5.0.0"
        }
        ],
        
      • Set the target to OnPrem.

      • Change the idRange to include all the IDs used by your test application (or leave blank).

    3. Copy all of the AL files that you generated for the test library in Task 5 to the root folder of your project.

    4. 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.
    5. Build the project.

    Next Steps

    If you are performing a technical upgrade from version 14.0 to version 15.0, return to the technical upgrade step where you left off.

    See Also

    The Txt2Al Conversion Tool
    Developing Extensions
    AL Development Environment
    Page Extension Object
    Report Object
    Page Properties