Upgrading Legacy Projects

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.

Additionally, all projects should be revalidated in a lab environment before deployment in the field. This revalidation step is essential to confirm that each component functions optimally in the new version, and we cannot guarantee a smooth upgrade if you attempt to update without lab testing.

Upgrade Command

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.

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

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

VB.NET:

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.

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

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

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.

Public Sub DisplayOpening()
	' Add your code here
	
End Sub

Public Sub DisplayIsOpen()
	' Add your code here
	
End Sub

Public Sub DisplayClosing()
	' Add your code here
	
End Sub

'This method is only called on Dialog displays
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
	Dim msg As String = @Client.Locale("Could not logon") + " (" + @Client.Locale(log.ToString()) + ")"
	MessageBox.Show(msg)
	Return False
End Function

Public Sub ExecuteLogOff(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
	@Client.LogOnGuest()
	@Display.LogOn.Close()
End Sub

Public Sub MouseLeftButtonOk(ByVal sender As Object, ByVal e As System.Windows.Input.InputEventArgs)
	 DialogOnOK()
End Sub

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.

Public Sub DisplayIsOpen()
End Sub

Public Sub DisplayClosing()
End Sub

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
	Dim msg As String = @Client.Locale("Could not logon") + " (" + @Client.Locale(log.ToString()) + ")"
	MessageBox.Show(msg)
	Return False
End Function

Public Async Function ExecuteLogOff(ByVal sender As Object, ByVal e As MouseButtonEventArgs) As Task
	Await @Client.LogOnGuestAsync()
	@Display.LogOn.Close()
End Function

Public Async Function MouseLeftButtonOk(ByVal sender As Object, ByVal e As System.Windows.Input.InputEventArgs) As Task
	Await DialogOnOK()
End Function

public void DisplayIsOpen() {
}

public void DisplayClosing() {
}

public async Task<bool> DialogOnOK() {
	eSecurityErrors log;
	log = (eSecurityErrors) await @Client.LogOnAsync(@Client.InputUserName, @Client.InputPassword);
	if (log == eSecurityErrors.OK) {
		@Display.LogOn.Close();
		return true;
	}
	string msg = @Client.Locale("Could not logon") + " (" + @Client.Locale(log.ToString()) + ")";
	MessageBox.Show(msg);
	return false;
}

public async Task ExecuteLogOff(object sender, MouseButtonEventArgs e) {
	await @Client.LogOnGuestAsync();
	@Display.LogOn.Close();
}

public async Task MouseLeftButtonOk(object sender, System.Windows.Input.InputEventArgs e) {
	// Add your code here
	await DialogOnOK();
} 

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.

In this section: