Work with the Business Central Performance Toolkit
The Business Central Performance Toolkit helps you track and compare performance between different builds of your solution to help ensure that changes in code don't negatively impact performance in customer tenants.
Business Central often serves as a scalable platform on top of which ISVs and VARs deliver vertical solutions and customizations for specific customers, and it's in everyone's interest to keep performance levels high. To keep customer tenants performant and current with major and minor updates in these solutions and customizations, we must ensure that changes in code don't negatively impact performance.
The Business Central Performance Toolkit helps you track and compare performance between different builds of your solutions. When onboarding new customers to Business Central, especially bigger customers, both the consultant and the customer must trust that Business Central is able to support current and projected loads to satisfy business needs. With the Business Central Performance Toolkit, consultants can simulate such loads and gain confidence in Business Central's ability to support specific customer loads.
The Business Central Performance Toolkit makes tools available to consultants as two extensions:
Business Central Performance Toolkit
Business Central Performance Toolkit Samples
The Performance Toolkit Extension
This extension is built for independent solution vendors (ISVs) and value added resellers (VARs) who develop vertical solutions and customize Business Central for their customers. In this type of collaboration, things often change between released versions on both sides, so it's important that ISVs and VARs can ensure that new versions of their solutions don't introduce performance regressions as the volume of users grows. To help, the Performance Toolkit lets developers simulate workloads in realistic scenarios to compare performance between builds of their solutions.
In short, the Performance Toolkit helps answer questions such as does my solution for Business Central support X number of users doing this, while other operations are happening. It doesn't answer questions such as, how many orders can Business Central process per hour.
It's important to remember that you can use the toolkit only in sandbox environments and Docker images. You can't use it in a production tenant.
The Performance Toolkit is two extensions, the Performance Toolkit, which is available for free on AppSource, and BCPT-SampleTests, which you can download from the ALAppExtensions repository on GitHub.
To get the full benefit of the toolkit, we recommend that you download and install both extensions.
To install the Performance Toolkit extension, follow these steps.
In your Sandbox environment, open the Extension Management page.
In the Extension Management page, select Manage, Extension Market Place.
In the page that opens, search on Performance Toolkit and select Get it now.
In the page that opens, enter your information and select Continue.
In the next page that opens, select Install.
In the confirmation page that opens, select Ok.
The Performance Toolkit is now installed.
To install the Performance Toolkit Samples, follow these steps:
Create a new AL project in VSCode.
In the app.json, set the dependencies as follows:
From the BCPT-SampleTests github location, download (or pull) the src folder into your project.
Renumber the objects into your object range, for example [50.000..99.9999].
In the TestCodeunitsWithParams.Enum.al file, make sure you renumber the enum values to match your object numbers:
Deploy the extension to your Sandbox.
If you use both extensions, they provide the following:
A framework for defining a set of tests or scenarios to run in parallel. The framework also logs results and lets you import and export suite definitions.
Predefined test suites that cover basic scenarios, which can also serve as inspiration for other suites that suit your customer environments.
A command line tool that must be installed on a client computer. To simulate multiple users signing in and using pages, you must start those scenarios from outside Business Central. The command line tool will run the number of concurrent client sessions that is specified in the suit.
Typically, you'll want to run the suite for multiple sessions at the same time. After you configure the suite, you can do that by using the Start action. However, if you want to do light-weight testing, for example, early in the development phase, you can choose the Start in Single Run mode action to run your suite just once, and as fast as possible. Single Run mode lets you monitor the number of SQL statements between runs and define baselines, and gives you quick feedback that can help identify regressions early on.
You can run up to 125 sessions at the same time for a test suite. The Total No. of Sessions field shows how many sessions will be created when you run the suite.
On the suite lines, the Run in Foreground option lets you run tests in sequence, rather than in parallel. You can also use it in combination with background tasks, but that will run each session individually. You can only run one session in the foreground at a time.
Configuring a Suite
The settings to configure a suite depend on the environment that you want to simulate. The following procedure provides an example for testing multiple sessions, but the steps also apply to a single run.
To configure a suite, follow these steps:
Search for BCPT Suites, and then select the related link.
Select New to open the BCPT Suite page.
In the Code, Description, and Tag fields, provide an identifier, some information about the test, and a tag that you can use to find the results of the suite on the Log Entries page.
Define timing for the run. The 1 Work Day Corresponds to field works with the Duration (minutes) field to update the Work Date Starts at field, and you use it to test processes that have deadlines, such as payments. The duration can be up to 240 minutes.
The Default Min. User Delay and Default Max. User Delay fields in the header let you simulate pauses between actions. You must specify a delay. Between each iteration, for example when creating sales orders, you can define a Delay (Delay between iterations) before the test starts on the next sales order. The delay can be Fixed or Random. Delays aren't included in the results for run times.
Specify the base version to compare. To change the value in the Base Version field, you might need to turn on Edit mode.
Configure lines for the suite. The lines will contain some of the settings from the header. Updating the values on the lines will also update the header.
On the BCPT Suite Lines FastTab, choose the codeunits to run.
In the Parameters field, enter a parameter to define iterations such as, for example, creating lines on documents. For example, a parameter Lines=10 will create 10 lines on a document.
In the No. of Sessions field, enter the number of concurrent users to simulate.
Optional: If you want to run in Single Run mode, or you want to run one of the sessions without applying settings such as minimum and maximum delays, select the Run in Foreground option.
Starting the Run from PowerShell
After you have installed the binaries and scripts and configured your suite, you can create the credential object and run the tests from PowerShell by using the following commands.
To create the credential object, run the following command:
$Credential = New-Object PSCredential -ArgumentList <user email>,(ConvertTo-SecureString -String <password> -AsPlainText -Force)
To start tests in a Business Central online sandbox, run the following command:
RunBCPTTests.ps1 -Environment PROD -AuthorizationType AAD -Credential $Credential -SandboxName <sandbox name> -TestRunnerPage 149002 -SuiteCode "TRADE-50U"
When you start tests from PowerShell, there is a two second delay between new sessions. When a run has completed, you can view the results on the lines on the BCPT Suite Lines FastTab.
After running the suite, you can choose Log Entries to see what happened. Use the Show Errors and Show sessions running at the same time as these actions apply filters to the results. For example, filtering can help troubleshoot errors by showing what a user was doing when an error occurred. By default, the page is filtered to show the latest version, but you can change or remove the filter if you want to compare runs. You can use the Open in Excel action to build dashboards that can help visualize performance results.
Log entries are listed in the order that they were created, which means that the different scenarios are mixed. Each run is identified by the value in the Version No. fields.
The Operation column shows the individual measurements, where the term Scenario is used for running the codeunit without the user wait time. The No. of SQL Statements column includes the SQL statements that were issued by the scenario and system activities, such as retrieving metadata. The counts exclude the log entries themselves. To drill down to a single session, filter on the Session No. field or choose Open in Excel to create a pivot table and pivot chart for deeper analysis.
Example: Evaluate SQL calls and timing in Single Run mode
This example shows how to use Single Run mode for performance regression testing (PRT) between changes to code, to evaluate SQL calls and timing.
Often, when developing a new extension, you start out with limited code and may want to wait to do a larger benchmark test with simulated concurrent users until you’re closer to having a full, end-to-end scenario.
You can use the Start in Single Run Mode action to perform a limited test, for example, on a new extension. Single Run mode will still provide things like a baseline, the ability to run the test in the background, and give you instant feedback.
The data that the runs generate is persisted in the database. If the database is maintained, you can set previous runs as baseline.
The following steps provide an example of how to run a PRT in Single Run mode.
On the BCPT Suites page, choose New.
In the Code field, enter a name for the test suite. In this example, we'll use PreTest.
In the Tag field, enter something that will make it easy to identify the suite later when you analyze the results.
The fields for duration and delays are not used for Single Run mode, so we'll leave their default values.
On the BCPT Suit Lines FastTab, choose the test suite for your component.
In this example, we're calculating the total weight of the items on a sales order, so we'll use the Sales Order page test with a parameter that creates four lines. The parameter should look as follows: Lines=4.
Clear the Run in Foreground option. This will run the test suite in a background thread.
Select Start in Single Run mode.
The following window should open.
Click the Refresh button to refresh the page.
When the test has completed, select Log Entries.
To set your baseline after the run completes, in the Base Version field, enter 1.
