Skip to content

Migrating Existing Workspaces to DataFlex 2026

DataFlex 2026 (26.0) is a major release for both the internal and external architecture of DataFlex. It introduces the DataFlex Package Manager and df-cli and moves the WebApp Framework out of the core product into the Web UI packages. Because of this, some workspaces — particularly large ones that have grown across many revisions — may need adjustments to their makepath and dependency tree during migration. Most workspaces migrate in a single pass. The forums and support are available if you need advice.

DataFlex core packages (such as Web UI) are served from the package server in production mode. Older versions of these packages are no longer selectable, but remain available to existing workspaces through their sws.lock files, so Beta 1 workspaces continue to work. This applies only to DataFlex core packages.

Follow the step-by-step plan below to make migration as smooth as possible.

0. Back Up or Use Version Control

Make sure your workspace is clean and has no un-backed-up changes before you start. Using a version control system (VCS) such as Git makes it much easier to review what the migration changed, spot unexpected edits, and recover if something goes wrong.

1. Migrate the Workspace

When you open an older workspace, the Studio starts the Workspace Migration Wizard automatically.

DataFlex 26.0 is version-agnostic toward packages and libraries: it reads both INI and JSON workspace files, and the version a file specifies no longer matters. This means you can keep the migration minimal even if your workspace currently has many global libraries or a complex structure that has grown over time.

  • Do not migrate your library workspaces through the wizard. Migrate only the root workspace you opened, preferably in place.
  • During the migration period, 26.0 will use your existing 25.0 library workspaces, which is fully supported — no breaking changes are expected in the Windows UI Framework.
  • After migration your .sws file is updated (it becomes JSON the first time it is written, so it may still be INI immediately after this step), or a new 26.0 .sws file is created.

If you make a copy of the workspace beforehand, migrating in place still lets you open the original copy in 25.0.

2. Web and FlexTron Applications

This step applies only to web and FlexTron applications. The entire WebApp Framework has been moved into a package called Web UI, with the variations Web UI Server and Web UI FlexTron.

After the Workspace Migration Wizard finishes, a separate one-time Web UI migration wizard appears. Before running it, stage all changes in your VCS or back up the workspace manually, so you can retry if the Web UI conversion fails.

  1. Pick the application type — FlexTron, Web, or both — and the theme you based your application on. Choose Install no theme if you went fully manual.
  2. Choose whether to remove DFEngine — this is almost always the case. The same applies to the CSS themes, unless you modified a default theme. If you did modify a default theme, also select Install no theme in the previous step, because the wizard will otherwise complain about user changes. You can always install a theme afterwards, so if you are unsure, leave it for later.
  3. Choose whether to modify index.html — the wizard removes DFEngine references and the CSS themes from it. If you use index.asp, the wizard cannot modify it automatically and you must make these changes yourself. If you used index.asp purely to version your JS and CSS dependencies, that is no longer needed — the Package Manager handles versioning for dependencies migrated to packages. Your web application should work once this step is complete.
  4. FlexTron only — 26.0 can add JS dependencies to FlexTron applications automatically. This requires a new FlexTronScriptIncludes.html file, which is included at compile time, so no deployment step is needed (unlike the web's index.html).
  5. Precompiled headers — change the precompiled header to a different name for the Web packages. If you use precompiled headers in other files as well, update those manually; in theory they can be removed altogether.

3. Compile and Run

Check that your application still compiles. If it compiles and runs, you are done.

If you get compile errors, determine whether they come from upstream changes. Some errors seen during migration were caused by developer code overriding private functions: Web UI has been refactored in preparation for 27.0, so a small number of changes may be required, though there should not be many.

In the worst case, the errors relate to the ordering of your dependencies. Before 26.0, the makepath was built exactly in the order you declared your dependencies, including all nested dependencies. In large projects that migrated across many versions with many libraries, the makepath may have worked only because the declaration order happened to be right — not because it matched the actual dependency tree.

3.1 MakePath and Dependency Trees

Build a valid dependency tree using these rules:

  • If your library overrides another library's functionality (a patch or otherwise), it depends on that library.
  • If your library adds functionality to another, it depends on that library.
  • If your library overrides files — the most common cause of makepath issues — it depends on the library whose files it overrides.
  • If your library overrides DAW's original Pkg\ files, create a library for it if you do not already have one and add it as a dependency. Sometimes your other libraries must depend on that wrapper as well. Even though it is a "leaf" library, it always supersedes the Pkg\ directory in the makepath.

Declaring these dependencies builds a valid dependency tree and guarantees that a makepath-order dependency always comes after the item that depends on it.

Dependency trees now matter in more places. For FlexTron and for web applications with an index.html, 26.0 generates the include statements for you, and the dependency tree drives their order — but here the tree is inverted: the lowest dependency (often the Web UI package) must come first so that everything depending on it works. Not every package has JS or other dependencies, but as these trees grow they become more important, so fix your dependency tree where needed. A correct tree also works in older versions and projects.

4. Post-Migration

At this point everything should work as it did before 26.0. To get the most out of 26.0:

  • Uninstall or unlink your local packages one at a time and migrate to the server-provided versions instead. This gives you updates and other capabilities over time. Do this at your own pace.
  • If you have libraries ("packages" when shared externally) that could be useful to others and are not yet available, consider pushing them to the server to share them.

5. Important Technical Notes

  • .sws and .sws.lock — the workspace now has an .sws file and an .sws.lock file. The .sws file always supersedes the lock file and specifies the constraints for packages; the lock file records the exact version currently selected within those constraints. Always consider them together, and always commit both to your VCS.
  • Held back — when the Studio shows that a version is "held back", another package or your workspace has constrained that package to a specific version or range.
  • Promoting — "promoting" moves a dependency from somewhere in your dependency tree to your root workspace. Only promote a package when your application depends on it directly.
  • Never promote Web UI — Web UI is tied bi-directionally to a specific version of Web UI Server or Web UI FlexTron. If you promote it, you cannot receive updates, because all newer versions will be marked as held back.
  • Web Control developers — depend on DataFlex-dev/Web UI#~1.0.0 or DataFlex-dev/Web UI#^1.0.0. This ensures compatibility and keeps the inclusion order correct.
  • The DfPkg directory — when you use packages, the Studio creates a DfPkg directory. Packages shown there do not necessarily exist there: at a lower level they are deduplicated, and what you see are references. The Package Manager copies a package only when needed; by default it creates links to avoid using extra space.
  • Global package cache — all dependencies are deduplicated in a global cache at C:\ProgramData\DataFlex\Packages\Cache. This is a new directory for DataFlex. It keeps a cache so packages are not installed side by side repeatedly, and it auto-prunes weekly once no links remain. The cache also lets you create a project while offline by falling back to the newest cached version, which is auto-suggested.
  • Version control — do not commit DfPkg or any AppHtml/*, DLL, or other files installed by the Package Manager to your VCS. Doing so unlinks and copies files to or from the repository and can cause conflicts. Commit them only to guarantee reproducibility, and only under exceptional circumstances.

See Also