Upgrading Solutions Reference

Upgrade solutions across platform versions.

Reference → Solution →  Solution Center → Creating | Managing | Server | Licensing | Upgrading

Upgrade Requirements

Version Compatibility

Important Notice

All projects must be revalidated in a lab environment before field deployment. This step is essential to confirm optimal functionality in the new version.

Upgrade Process

Steps

1. Place <project>.tproj file in SolutionCenter folder
2. Press Refresh in Solution List
3. Legacy project appears with "Project." prefix
4. Select project and click "Upgrade Version"
5. System creates .dbsln file with same name
6. Original .tproj file remains intact
7. Designer prompts for Build on first opening

File Handling

Automatic backup on every upgrade (10.1.5+)

Starting with 10.1.5, every upgrade creates a preserved backup of the original solution file next to the solution itself. You do not need to copy the file manually before running the upgrade. The backup filename encodes the source version.

For example, upgrading Plant.dbsln from an earlier 10.1.x release leaves your solution folder containing:

Legacy .tproj upgrades continue to behave the same as in earlier releases: the original .tproj file stays on disk untouched and acts as its own rollback copy.

If the upgrade fails (10.1.5+)

When an upgrade does not complete successfully, 10.1.5 guarantees:

• Your original solution file is left exactly as it was. The upgrade process never deletes or overwrites the source on failure.
• The backup copy created at the start of the run is also kept on disk, even though the upgrade did not finish. You can re-run the upgrade after fixing whatever condition caused the failure.

The Solution Center displays a failure dialog that includes the full path to the upgrade log file (typically %PUBLIC%\Documents\FrameworX\TraceLogs\UpgradeLog.txt). Open the log to see the exception detail that caused the failure.

Warnings logged during a successful upgrade (10.1.5+)

An upgrade can complete successfully while still logging individual non-fatal warnings — for example, a single table cell whose legacy value cannot be mapped to the new schema. When this happens, the Solution Center displays a count on the Upgrade Concluded dialog:

N exception(s) logged during upgrade. Open log file

Click Open log file to launch the upgrade log in your default text editor. Each logged entry includes:

• The upgrade step that produced the warning (for example, CopyMembers cell convert [DisplaysListContents.Xaml]).
• The full exception message and stack trace.

Review the logged warnings as part of your pre-production validation. Most are informational — a row or cell that could not be automatically migrated — and can be resolved by hand in the Designer after the upgrade.

Command-line upgrade — SolutionUpgrade.exe (10.1.5+)

The headless upgrade utility SolutionUpgrade.exe (shipped in the FrameworX program folder) prints exception details directly to the console instead of surfacing only the aggregate count. Typical output:

> SolutionUpgrade.exe "C:\Projects\Plant.dbsln"
Upgrading: C:\Projects\Plant.dbsln
Previous version: fs-10.1.4-12345
Backup file: C:\Projects\Plant_fs-10.1.dbsln
[  5%] Preparing table 'UserTypesContents'...
[ 78%] Copying source tables to target...
Upgrade finished.
Exceptions during upgrade: 1

--- UpgradeLog.txt (this run) ---
2026-04-21 10:32:14 ****** Upgrade started: C:\Projects\Plant.dbsln ******
2026-04-21 10:32:16 Exception on CopyMembers cell convert [DisplaysListContents.Xaml]: ...
2026-04-21 10:35:02 ****** Upgrade finished: C:\Projects\Plant.dbsln ******
--- end of log ---
Full log: C:\Users\Public\Documents\FrameworX\TraceLogs\UpgradeLog.txt

Exit codes:

Manual Corrections Required

RuntimeUsers Database

Issue: Table name change from EditSecurityUsers_Runtime to SecurityRuntimeUsers

Required Action:

1. Rename table in target database
2. Update from EditSecurityUsers_Runtime
3. Change to SecurityRuntimeUsers
4. Complete before production deployment

Advanced Toolkit Applications

Applications using programmatic engineering (EngWrapper API) may lack compatibility due to internal structure changes. Contact support for upgrade assistance.

Themes

Review screens and objects mapped to theme resources after upgrade.

Asynchronous Methods

Version 10.1 or newer uses async programming patterns for improved performance and HTML5 compatibility.

Required Changes

Server Class Calls from Client

C# Example:

public async Task DisplayOpening()
{
    await @Script.Class.ServerMain.Method1();
}

VB.NET Example:

Public Async Function DisplayOpening() As Task
    Await @Script.Class.ServerMain.Method1()
End Function

LogOn Method Update

Replace LogOn() with LogOnAsync():

JavaScript:

this.DialogOnOK = async function()
{
    var result = await @Client.LogOnAsync("user1", "pass1");
    return true;
};

C#:

public async Task<bool> DialogOnOK()
{
    var result = await @Client.LogOnAsync("user1", "pass1");
    return true;
}

VB.NET:

Public Async Function DialogOnOK() As Task(Of Boolean)
    Dim result As Integer = Await @Client.LogOnAsync("user1", "pass1")
    Return True
End Function

Complete CodeBehind Example

Legacy Code (Synchronous):

Public Function DialogOnOK() As Boolean
    Dim log As eSecurityErrors
    log = DirectCast(@Client.LogOn(@Client.InputUserName, @Client.InputPassword), eSecurityErrors)
    If log = eSecurityErrors.OK Then
        @Display.LogOn.Close()
        Return True
    End If
    Return False
End Function

Updated Code (Async):

Public Async Function DialogOnOK() As Task(Of Boolean)
    Dim log As eSecurityErrors
    log = DirectCast(Await @Client.LogOnAsync(@Client.InputUserName, @Client.InputPassword), eSecurityErrors)
    If log = eSecurityErrors.OK Then
        @Display.LogOn.Close()
        Return True
    End If
    Return False
End Function

Additional Corrections

Symbol Mnemonic

All mnemonics require default values:

Popup Position

Use Drawing Properties for positioning:

• Path: Drawing → Display → [DisplayName] → Drawing Properties
• Settings: Left and Top

Layout System

Projects from 9.2 or older versions that did not use the last screen in the layout list as the dynamic screen, which automatically switched screens with an open command and therefore needed to use the OpenAtIndex command, must have their layouts reconfigured, because in a migration to 10.1 or newer, the last screen in the layout list will be considered the main switching screen.

Display WPF only no longer automatically converts LayoutTransform (rotation used in 8.1 version that doesn't work for HTML5) to RenderTransform (rotation used in v10 that is used for WPF and HTML5), it keeps as LayoutTransform. However, if the user ungroups symbols, groups, and shape groups that have LayoutTransform, or removes the Transform, the LayoutTransform will be lost.

Deprecated Features

Validation Checklist

Pre-Production Testing

• All displays open correctly
• Scripts execute without errors
• Database connections work
• Alarms function properly
• Historical data logs correctly
• Client connections stable
• Performance acceptable

Common Issues

Best Practices Checklist

• Backup original project before upgrade
• Test thoroughly in lab environment
• Document all manual changes made
• Verify async methods in all scripts
• Review deprecated features for alternatives
• Plan theme and layout updates
• Validate all functionality before production

In this section...