Dynamics 365 Business Central: Debugging Upgrade and Install code in Visual Studio Code

Hi, readers.
If you have checked the Changelog of AL Language, you could find the following update.

Debugging Upgrade and Install code

It is now possible to debug upgrade and install codeunits. A new command “Publish extension without building” has been introduced that will allow for apps to be published while debugging. To debug upgrade or install code, first initiate an attach debug session. After the debugger has attached, invoke the new command or use Ctrl+F5 to publish the app file. If the version of the app has not been incremented, install codeunits will be invoked. If the version of the app has been incremented, or the forceUpgrade flag has been set to true in the launch.json file, upgrade codeunits will be invoked.

https://marketplace.visualstudio.com/items/ms-dynamics-smb.al/changelog

Yes, you can debug upgrade and install codeunit from Business Central 2020 release wave 2 update (BC17).
The documentation is very concise, In this blog, I will do a detailed step by step description.

Let’s start.

First initiate an attach debug session, so you have to modify “launch.json” file of project.
Request: “attach”

“breakOnNext”: “WebServiceClient”

PS: Attach is only supported for WebServiceClient
[2020-10-06 10:18:51.36] Attach is only supported for ‘WebService’ client types on sandbox debugging.

Upgrade Codeunit:

1. Set at least one breakpoint in the upgrade codeunit.

2. Then package the project.

PS:
If you forget package the and the version of the app has been incremented, you will get an error when running “Publish extension without building”.

[2020-10-06 10:40:38.24] Error: File c:\Users\yzhu\Documents\AL\HelloWorld\Purchase-Invoice-Camera\ZHU YUN_Business Central Sample Extension_1.0.0.5.app does not exist.

3. Run the attach launch target in debug

The debug connection is successful.

4. Run new command “Publish extension without building”

Now you can debug Upgrade code.

Install Codeunit:

1. Set at least one breakpoint in the install codeunit.

2. Run the attach launch target in debug.

3. Run new command “Publish extension without building”

Now you can debug Install code.

PS: if you get following error, please try to increment the version.

[2020-10-06 11:20:55.48] The request for path /v2.0/Sandbox/dev/apps?SchemaUpdateMode=synchronize&ForceUpgrade=true&DependencyPublishingOption=ignore failed with code UnprocessableEntity. Reason: A duplicate package ID is detected. Cannot publish an extension with packageId: ’48c0cf0b-dcdd-423c-a1ff-f96ace66cd0b’, appId: ‘e4a51fd0-a71b-4fad-8d5c-796956d250a1’, name: ‘Business Central Sample Extension’, publisher: ‘ZHU YUN’ and version: ‘1.0.0.5’, because the same package ID already exists in a published extension with packageId: ’48c0cf0b-dcdd-423c-a1ff-f96ace66cd0b’, appId: ‘e4a51fd0-a71b-4fad-8d5c-796956d250a1’, name: ‘Business Central Sample Extension’, publisher: ‘ZHU YUN’ and version: ‘1.0.0.5’.

PS:
If the version of the app has been incremented, or the forceUpgrade flag has been set to true in the launch.json file, upgrade codeunits will be invoked.

Update 2020/12/10

You can also debug in the On-Premises version.
For example: Install Codeunit

launch.json: For reference only.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "al",
            "request": "attach",
            "name": "On-Pre attach",
            "environmentType": "OnPrem",
            "server": "http://localhost",
            "serverInstance": "BC171",
            "authentication": "Windows",
            "port": 7049,
            "breakOnError": true,
            "breakOnRecordWrite": false,
            "enableSqlInformationDebugger": true,
            "enableLongRunningSqlStatements": true,
            "longRunningSqlStatementsThreshold": 500,
            "numberOfSqlStatements": 10,
            "breakOnNext": "WebServiceClient"
        },
        {
            "name": "On-Premises",
            "type": "al",
            "request": "launch",
            "environmentType": "OnPrem",
            "server": "http://localhost",
            "serverInstance": "BC171",
            "authentication": "Windows",
            "port": 7049,
            "breakOnError": true,
            "breakOnRecordWrite": false,
            "launchBrowser": true,
            "enableSqlInformationDebugger": true,
            "enableLongRunningSqlStatements": true,
            "longRunningSqlStatementsThreshold": 500,
            "numberOfSqlStatements": 10,
        }
    ]
}

END

Hope this will help.

Thanks.