Upgrading to SftTree/NET 3.0

SftTree/NET 3.0 is source code compatible with SftTree/NET 2.0. An application is upgraded by replacing its SftTree/NET 2.0 assembly references with a reference to the SftTree/NET 3.0 assembly and rebuilding it; the application code does not change. Forms designed with SftTree/NET 2.0 and documents saved by SftTree/NET 2.0 load unchanged. This topic describes the upgrade of a .NET Framework application step by step and what an upgraded application may notice at run time.

Requirements

• Visual Studio 2019 or later. SftTree/NET 2.0 supported Visual Studio 2005 through 2019.
• .NET Framework 4.7 or later, or .NET 10 or later. SftTree/NET 2.0 required the .NET Framework 2.0, so an application targeting an older .NET Framework version is retargeted as part of the upgrade.
• A SftTree/NET 3.0 license. SftTree/NET 2.0 licenses do not apply to version 3.0. The SftTree/NET 3.0 demo cannot open forms and documents created with a licensed version of SftTree/NET; it reports "The demo version cannot be used to open projects created using the licensed version of this product."

Before upgrading, make sure the projects are under source control or backed up. Once a form or a document has been saved with SftTree/NET 3.0, it can no longer be opened with SftTree/NET 2.0.

SftTree/NET 2.0 and 3.0 on the Same System

SftTree/NET 3.0 installs side by side with SftTree/NET 2.0, so applications can be upgraded one at a time:

• SftTree/NET 3.0 installs into \Program Files (x86)\Softelvdm\SftTree NET 3.0\; SftTree/NET 2.0 stays in \Program Files (x86)\Softelvdm\SftTree NET 2.0\.
• Both versions use the assembly name Softelvdm.SftTreeNET and the same strong name key, with different assembly versions (2.0.x and 3.0.0.0), so both can be registered in the Global Assembly Cache. An application binds to the version it references.
• The licensing DLLs and license files of the two versions are separate.
• Setup adds the SftTree/NET 3.0 control to the Toolbox tab "Softel vdm, Inc." of Visual Studio 2019, 2022 and 2026 and replaces a SftTree entry already in that tab. To keep using SftTree/NET 2.0 in Visual Studio 2019 for a project that is not upgraded yet, add the 2.0 control to the Toolbox again from \Program Files (x86)\Softelvdm\SftTree NET 2.0\Bin\, see Manually Adding .NET Components To The Toolbox.

One application cannot use both versions: they use the same namespaces and type names, so a project references either SftTree/NET 2.0 or SftTree/NET 3.0.

Upgrading a .NET Framework Application

1. Target Framework

If the project targets a .NET Framework version older than 4.7, change its target framework to .NET Framework 4.7 or later in the project properties.

2. References

In Solution Explorer, expand References and remove the references Softelvdm.Controls and Softelvdm.SftTreeNET. Then add a reference to the SftTree/NET 3.0 assembly: in the Reference Manager, select Assemblies > Extensions and check Softelvdm.SftTreeNET, version 3.0.0.0, or click Browse and select \Program Files (x86)\Softelvdm\SftTree NET 3.0\Bin\Softelvdm.SftTreeNET.dll.

In the project file (.csproj, .vbproj), the two SftTree/NET 2.0 references

<Reference Include="Softelvdm.Controls, Version=1.0.0.0, Culture=neutral, PublicKeyToken=25c3069afccab10e, processorArchitecture=MSIL">
  ...
</Reference>
<Reference Include="Softelvdm.SftTreeNET, Version=2.0.21.0, Culture=neutral, PublicKeyToken=25c3069afccab10e, processorArchitecture=MSIL">
  ...
</Reference>

(the version depends on the SftTree/NET 2.0 release used) become one reference to SftTree/NET 3.0, for example:

<Reference Include="Softelvdm.SftTreeNET, Version=3.0.0.0, Culture=neutral, PublicKeyToken=25c3069afccab10e, processorArchitecture=MSIL">
  <SpecificVersion>False</SpecificVersion>
  <HintPath>C:\Program Files (x86)\Softelvdm\SftTree NET 3.0\Bin\Softelvdm.SftTreeNET.dll</HintPath>
</Reference>

The using directives (C#) and Imports statements (Visual Basic) for the namespaces Softelvdm.SftTreeNET and Softelvdm.Controls stay as they are. Both namespaces are now in the one assembly Softelvdm.SftTreeNET, so the Softelvdm.Controls reference is no longer needed.

3. Rebuild

Rebuild the project. SftTree/NET 2.0 code compiles unchanged, with one exception: the parameter of HeadersClass.RemoveAt and FootersClass.RemoveAt, a row index, is named RowIndex (SftTree/NET 2.0: ColIndex). Code that passes it as a named argument must use the new name.

4. Forms

Forms designed with SftTree/NET 2.0 need no changes. The tree contents (items, headers and footers) saved in the form's .resx file load unchanged, in the designer and at run time, and the form's design-time license information stays valid for the distributed application. When a form is saved in the designer, its tree contents are written by SftTree/NET 3.0 and the form can no longer be opened with SftTree/NET 2.0.

5. Distributed Files

Ship the SftTree/NET 3.0 assembly Softelvdm.SftTreeNET.dll from \Program Files (x86)\Softelvdm\SftTree NET 3.0\Redist\ with the application, in place of the SftTree/NET 2.0 files Softelvdm.SftTreeNET.dll and Softelvdm.Controls.dll. The publisher policy assemblies Policy.2.0.Softelvdm.SftTreeNET.dll and Policy.1.0.Softelvdm.Controls.dll and their .config files, if the application's setup installed them, are no longer needed. See Distributing SftTree/NET.

Saved Documents

Documents saved by a SftTree/NET 2.0 application with GetContents load with SetContents in a SftTree/NET 3.0 application for the .NET Framework, including their images and fonts. Documents saved by SftTree/NET 3.0 cannot be loaded by SftTree/NET 2.0.

What Changes at Run Time

An upgraded application looks and behaves as before. The new features are off by default: DarkMode and HighContrastMode are Off, ImageScaling and PixelScaling are AsIs, and per-monitor DPI awareness applies only to applications that declare it. Screen readers are supported without any change to the application. For the new features, see New Features.

Differences from SftTree/NET 2.0 that an upgraded application may notice:

• The CheckBoxClicked event reports the cell for a check box in a cell and the row header for a check box in a row header. SftTree/NET 2.0 reported the row header for a check box in a cell and neither for a check box in a row header.
• The splitter bar is drawn as a slider track, like SftTree/DLL, instead of a slider thumb, which is a solid blue block on Windows 10 and 11.
• The column resizing and reordering cursors are the system cursors; they are no longer stretched at display scaling above 100%.
• Reset in the property grid restores the actual default values of the selection and hover colors; SftTree/NET 2.0 applied different colors for ten of them.
• Contents saved with GetContents load back as saved: HorizontalExtent, HorizontalOffset and the width of an open-ended last column no longer change with each save and load.