X++ classes that implement the SysSetup interface are processed as part of database synchronization. Custom X++ classes that implement SysSetup are also run as part of database synchronization.
Attributes provide a powerful way to associate metadata, or declarative information, with code such as assemblies, types, methods, and properties. After an attribute is associated with a program entity, it can be queried at runtime by using reflection.
This article describes how to use the new SysSetupConfigAttribute attribute that the platform updates for version 10.0.23 of finance and operations apps introduce for X++ classes that implement the SysSetup interface.
What Are SysSetup Classes?
SysSetup is an interface in X++ that allows certain classes to run during database synchronization. These classes can perform tasks like setting up initial data. When you create a custom class that implements SysSetup, it is also included in this synchronization process.
Purpose of SysSetupConfigAttribute
This attribute gives developers the ability to:
Control how a
SysSetupclass behaves during synchronization.Avoid failures that could block the sync process.
Define how long a script should run.
Enable version control to prevent repeated execution.
How to Use SysSetupConfigAttribute
You must decorate every X++ class that implements the SysSetup interface with this attribute. It accepts the following parameters:
1. ContinueOnError (Boolean)
true – If the script fails, database sync continues.
false – If the script fails, database sync stops until the issue is resolved.
2. Timeout (Integer)
Defines how long (in seconds) the script can run.
Valid range: 1 to 600 seconds.
Example:
[SysSetupConfigAttribute(true, 300)]
class DemoClass implements SysSetup
{
// Class implementation
}
ContinueOnError = trueTimeout = 120 seconds
Running SysSetup Scripts Asynchronously
To improve performance and reduce dependencies, SysSetup scripts can also be executed asynchronously using batch jobs. For this, extend the SysSetupAsync class and use SysSetupWrapper to schedule execution.
class DemoClass extends SysSetupAsync implements SysSetup
{
// Asynchronous script logic
}
Considerations for Asynchronous Execution
No timeout limit (relies on batch job system).
Runs in high-priority batch scope.
Doesn’t support
ttsbegin;/ttscommit;blocks — you need to manage transactions manually.Ideal for smaller workloads that can resume if paused.
Versioning Support for SysSetup Classes
Starting from version 10.0.27, you can version your SysSetup classes using an additional _version parameter. This helps ensure that your script runs only once per version, rather than on every database sync.
How Versioning Works
Syntax:
[SysSetupConfigAttribute(true, 120, "2.1")]Format:
Major.Minor(e.g., 1.0, 2.1, 10.4)Default version: 1.0 (if not provided)
If the version changes, the script runs again. If not, it won’t rerun during future syncs.
Special Version: 0.0
If you want the script to run every time DBSync is executed, set
_versionto 0.0.
Best Practices for Using SysSetupConfigAttribute
Always use this attribute on all
SysSetupclasses to clearly define behavior.Prefer using versioning to control repeated execution.
Use asynchronous mode for heavy operations to boost performance and reduce dependency issues.
If you’re onboarding a new SysSetup class, include the
_versionparameter to avoid unexpected behavior.
Summary
The SysSetupConfigAttribute is a powerful way to control how setup scripts behave during database synchronization. By using its parameters wisely—ContinueOnError, Timeout, and _version—you can improve stability, performance, and manageability of your X++ SysSetup classes in Dynamics 365.