Understanding SysSetupConfigAttribute in Dynamics 365 (X++)

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.

Sharing Is Caring:

Leave a Comment

Top 30 JavaScript Interview Questions and Answers for 2024 Top 5 Front-End Web Development