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
SysSetup
class 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 = true
Timeout = 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
_version
to 0.0.
Best Practices for Using SysSetupConfigAttribute
Always use this attribute on all
SysSetup
classes 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
_version
parameter 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.