Upgrading Legacy Projects

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, the bring to the final step on version 10.

When a file with 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 of in the upgrade process. 
• A new solution (extension dbSln) is created with the same name of 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 a few areas that a manual interface is necessary.

RuntimeUsers Database, TableName

The pre-defined value for the table name for RuntimeUsers is version 9.2 or older was: EditSecurityUsers_Runtime. That name was replace by SecurityRuntimeUsers. 

The Upgrade tools already tries to find and correct that name in Scripts and Database connections automatically, but the DATABASE itself you will be connecting, we can't change automatically. Therefore, before commission the version 10 to production, you need to rename the name is the target database, from EditSecurityUsers_Runtime to SecurityRuntimeUsers

Advanced Toolkit applications

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

Themes

The Themes features from 9.2 allowed extensive customization, with the drawback that could be quite complex to manage. 

The Themes features of version was expanded, with more built-in themes, and extremely simplified, but the migration can't be fully automated. Those solutions needs to have a review on the colors of screen and objects that were mapped to theme resources. 

Scripts Asynchronous Methods

Version 10 uses a more modern and efficient programming pattern that is Asynchronous methods. That allows better performance on displays, and it is one the technologies that enabled most of Windows WPF displays, to run also on WEB HTML5 with no modifications. 

When creating new solutions, that is done automatically for you, but legacy Displays that had heavy CodeBehind Scripts, may need to the methods modified 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 there async versions. 

Here is the modification 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

On the of reasons the update of the code to use async is not fully automated, it's that when on method is modified to became async, the other methods calling. that one, should be updated also, at its signature and return value is now a new one. There are different ways to implement it, typically using await or Result operators; it wouldn't be passible to the upgrade tool to automatically and safely modify all dependencies and logic of the applicatoin 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 still can be used in Displays that are WPF (Windows) only.

The reason for the warnings is that code is no longer acceptable for pages targeting Web Html5. Therefore they can't either be use in Portable pages (Web and Windows ready), which the preferred option moving forward.  

It's important to emphasize that using async has also benefits on WPF-Windows as it makes the UI interactions even more responsive.

Here is Code Behind after the modifications, to use async methods.

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();
} 

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

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, and allowing different solutions to have distinct IDs for the theme resources, whDirect ich are now standard. 
• Direct Access and mapping to external TagProvider data, without define its position on the AssetTree.
• XPS: generation and visualization for XPS documents is no longer used.

In this section: