When dealing with long processes, Microsoft Dynamics 365 Business Central provides some tools to mitigate the wait and provide a better user experience. In this post, I will show you how to run a background process using the StartSession function.
- What Is The StartSession Function In Business Central?
- Considerations For Using StartSession
- Example Of Using StartSession
- Limitations
- Bonus
What Is The StartSession Function In Business Central?
The StartSession function allows to initiate a new Business Central session in parallel. This session doesn´t have a user interface. It runs in the background and allows to run heavy operations without blocking the user interface. Unlike Page Background Tasks it can perform both read and write transactions.
Learn more about Page Background Tasks in the following article.
Considerations For Using StartSession
Resources
As stated above, a background session is a normal session but without user interface. This means that you should be aware of the implications.
As the Microsoft documentation reads:
Each background session has the same impact on resources as a regular user session. In addition, it takes time and resources to start each background session. Therefore, we recommend that you consider when and how you use background sessions. For example, do not use background sessions for small tasks that occur often because the cost of starting the session for each tasks is high.
In other words, keep this function for heavier calculations that don´t need to be run very frequently.
Get more information about the StartSession function in the Microsoft documentation below.
Be Careful With It
As Waldo points out, you could end up crashing the service if handled inappropriately. Also, if a server restart occurs the process running will be stopped.
Dialogs
Another point to keep in mind is that dialog boxes will be suppressed during the background session. This table shows how they are handled:
Example Of Using StartSession
To use the StartSession function we have to do two things.
- Create a codeunit that will hold the code
- Call the codeunit with StartSession
The first thing we need is the codeunit that will run the code. Place the code in the ‘OnRun’ trigger like the example below. This is a very basic example that will change the ‘Blocked’ state of all the customers in the company.
Now, we will use the StartSession function to run the code in the background.
The first parameter is the SessionID variable, which is the return ID of the background session. And the second parameter is the CodeUnit to run. A simple example can look similar to this one.
Note that the ‘Ok’ variable is used to inform if the session was started successfully or not.
Limitations
With the StartSession function, we get some limitations. Let´s have a look.
Debugging
We can only debug a background session on Business Central On-premise. For the Saas environment this feature is not supported.
We can do it On-premises by using the Attaching feature.
In short, we can debug a background session by following two simple steps.
- Add the ‘attach’ configuration
- Debug and attach session
Add the following configuration to the launch.json file:
Once you start debugging (F5), you can attach a new session. To initiate it, first go to the debug section in Visual Studio Code and then, choose the configuration just created. Finally, click on the play button.
Now, when you execute the code the debugger will stop on any breakpoint in the background session. It will also break on errors.
You can learn more about attaching and debugging in the Microsoft documentation below.
Attach and Debug Next – Business Central | Microsoft Docs
ErrorHandling
Secondly, the StartSession function doesn´t have any error handling parameter.
The return value of the function just shows if the session could initiate. But doesn´t tell if the whole process was successful or not. For this purpose, we need to make some customizations.
The ‘operation’ stated in the documentation just refers to the initialization of the background session. And not the outcome of the process.
Bonus
In a Saas environment, you should be able to see the background session running in the Admin Center. If you want to learn more about the Admin Center and its capabilities check the following article.
As you can see in this image, there is a session with ‘Background Client’ as the Client Type. When the process finishes it´s closed automatically.
For On-premises you can look into the Active Session list by adding to the URL the part in bold:
http://localhost:8080/BC200/?table=2000000110
That´s all. Hope you find it useful.