Page History

Upgrade solutions across platform versions.

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

Upgrade Requirements

Version Compatibility

Important Notice

All projects must

Upgrading to v10: Important Notice

The new Version 10 is a major update, introducing significant improvements and new technologies to enhance performance, security, and future platform support. Due to the extent of these changes, upgrading existing projects to V10 may require some manual adjustments to ensure compatibility.

be revalidated in a lab environment before field deployment

. This

step is essential to confirm

optimal functionality in the new version

.

Upgrade

In order to upgrade a legacy project, you just need to put the <project>.tProj file in the folder mapped to the Solutions Manager, so that project will be visible on the Solutions List (press Refresh after changing files in the folders).

Only projects from versions 9.1 and 9.2 can be upgraded directly. For older project files, first use the 9.1 or 9.2 product to upgrade to that version, then bring it to the final step on version 10.

When a file with the extension .tProj is found, it shows on the Solution List with the prefix "Project." When a legacy project is selected, the "Upgrade Version" command button is enabled.

When Upgrading:

• The previous project file remains intact; the system uses a copy in the upgrade process.
• A new solution (with the .dbSln extension) is created with the same name as the upgraded project (only the extensions of the file will be distinct).
• After the upgrade, only the new solution (.dbSln) will show on the Solution List (the legacy project file is kept hidden from the list).

The first time you open an imported solution, the Designer will prompt you to do a Build Command (Runtime → Build and Publish).

Manual Upgrade Corrections

Most of the replacement of new names and properties is executed automatically, but there are a few areas where manual intervention is necessary.

RuntimeUsers Database, TableName

The pre-defined value for the table name for RuntimeUsers in version 9.2 or older was: EditSecurityUsers_Runtime. This name has been replaced by SecurityRuntimeUsers.

The Upgrade tools already attempt to find and correct that name in Scripts and Database connections automatically, but the DATABASE itself you will be connecting to cannot be changed automatically. Therefore, before commissioning version 10 to production, you need to rename the table in the target database from EditSecurityUsers_Runtime to SecurityRuntimeUsers.

Advanced Toolkit applications

Some advanced applications using the product toolkits and the API for programmatic engineering (EngWrapper API) are likely to lack compatibility due to the renaming of internal data structures and tables. Contact support if upgrading such applications.

Themes

The Themes features from version 9.2 allowed extensive customization, but managing them could be quite complex.

The Themes features in version 10 have been expanded, with more built-in themes and an extremely simplified interface. However, the migration cannot be fully automated. Solutions need to be reviewed for the colors of screens and objects that were mapped to theme resources.

Process

Steps

1. Place <project>.tproj file in Solutions Manager 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

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:

csharp

public async Task DisplayOpening()
{
    await 

Scripts Asynchronous Methods

Version 10 uses a more modern and efficient programming pattern called asynchronous methods. This improves performance on displays and is one of the technologies that enables most Windows WPF displays to run on web HTML5 with no modifications.

When creating new solutions, this is done automatically for you. However, legacy displays with heavy CodeBehind scripts may require modification of methods to use the async operator.

For more information on Async programming: https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/

Calling Server Classes from Displays and Client Classes

 Now when calling Script Class Server method from Client scripts (Script Class Client or Display CodeBehind) should add "await" (C#) "Await" (VB.NET) for the HTML5 to work successfully.

C#:

@Script.Class.ServerMain.Method1();
}

VB.NET Example:

vbnet

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

Correction of Logon() on CodeBehind

The method Logon() should be replaced by LogonAsync(), as well other synchronous methods shall be modified to their async versions. Here is the modification of the Logon() method, as it was very commonly used in the projects.

LogOn Method Update

Replace LogOn() with LogOnAsync():

JavaScript:

javascript

this.DialogOnOK = async function()
{

 var result = await 

@Client.LogOnAsync("user1", "pass1");

 return true;
};

C#:

csharp

public async 

Task<bool> DialogOnOK()
{

 var result = await @Client.LogOnAsync("user1", "pass1");

 return true;
}

VB.NET:

vbnet

Public Async Function DialogOnOK() As Task(Of Boolean)

 Dim result As Integer = Await @Client.LogOnAsync("user1", "pass1")

 Return True
End Function

Calling Async Methods

One reason the update of the code to use async methods is not fully automated is that when a method is modified to become async, other methods that call it need to be updated as well. These calling methods must also be updated in their signatures and return values to accommodate the new async method. There are different ways to implement this, typically using await or Result operators. It would not be feasible for the upgrade tool to automatically and safely modify all dependencies and application logic to use the method asynchronously.

Here ia complete example, on how a Code Behind of a display was in earlier versions, with synchronous call, and the modified code using async calls.

Complete CodeBehind Example

Legacy Code (Synchronous):

vbnet

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):

vbnet

Public 

The previous code in version 10 will issue warnings, not errors, as it can still be used in displays that are WPF (Windows) only.

The warnings are issued because the code is no longer acceptable for pages targeting Web HTML5. Therefore, it cannot be used in portable pages (Web and Windows ready), which are the preferred option moving forward.

It’s important to emphasize that using async also benefits WPF-Windows applications by making UI interactions more responsive.

The upgrade tool will only attempt to automatically update the LogOn page if it was kept as provided in the templates. The following code shows the changes needed to manually correct the LogOnPage if necessary, and the patterns of using async and await can be applied to other pages that require changes.

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

A suggestion to change certain methods to async will appear during the build process in Runtime / Build and Publish.

Symbol Mnemonic

As of version 9.2, all mnemonics in symbols are required to have a default value. This configuration can be set either prior to the upgrade or after upgrading to version 10. Objects should follow the standard format shown below where Expression represents how it was defined in previous versions, while Label Text reflects the format in version 10. These names correspond to the property names. The example shown refers to the TTextBox object within the TextIO property.

Popup position

The procedure for positioning popups on the display has changed. Use the 'Left' and 'Top' settings under Drawing Properties

Full path: Drawing / Display / <DisplayName> / Drawing Properties / Display Settings: "Left and Top"

Layout

In previous versions, layouts relied on docking and alignment. The layout system has since changed—please refer to the layout section for details on the new approach: Displays Layouts

Projects that previously used multiple docked windows (e.g., docking to the top to create multi-level menus) can no longer be set up this way. In the new version, all menu levels must now be included within a single header window.

To modify specific submenu sections within the header, use the ChildDisplay control to create and manage submenu levels. The number of ChildDisplay elements should match the number of desired levels. Alternatively, you can create multiple header displays with the required variations. While this approach is more labor-intensive, it may be suitable when there are only a few combinations.

Deprecated Features

List of Deprecated features:

• Synchronous calls on SQL Queries and various other methods. The system will still compile, but a warning will be issued.
• Custom Theme Editing for specific controls is no longer support. We also no longer allow different solutions to have distinct IDs for the theme resources, as those are now standard. 
• The syntax <TagProvider>.("Topic Path") is no longer supported. You now need to map the TagProvider to the AssetTree.
• Generation and visualization for XPS documents is no longer supported.

 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.

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...

In this section: