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 versions — 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 guidance.

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 has been changed by the migration process, spot unexpected modifications, and recover if something goes wrong.

1. Migrate the Workspace

When you open a workspace created in a previous version of DataFlex, 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 to a minimum even if your workspace currently uses many global libraries or has 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, 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 choose to migrate a copy of the workspace, or make a copy of the workspace beforehand and migrate it in place, you may still open the original workspace 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 dialog appears. Before going through the presented options, stage all changes in your VCS or back up the workspace manually, so you can retry if for some reason the Web UI conversion fails.

  1. Install Package(s) — Pick the package(s) appropriate for the application type - Web (Web UI Server), FlexTron (Web UI FlexTron), or both — and the theme you based your application on. Choose Install no theme if you use your own custom theme and not one of DataFlex standard themes.
  2. Remove Files from AppHtml — Choose whether to remove DFEngine and the default CSS themes stored in CSSThemes, which is almost always the case, unless you modified a default theme. If you did modify a default theme, deselect the option to remove CSSThemes and also select Install no theme in the previous option, otherwise you will see messages about user changes when concluding this process. You can always install a theme afterwards, so if you are unsure, proceed without installing any themes and install them at a later time.
  3. Adjust Index.html — Choose whether to modify index.html and allow this process to remove DFEngine references and the CSS themes from the index.html of the workspace. If you use index.asp, that cannot be adjusted 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 completed. You may preview the changes that will be applied to this file by clicking on the Preview link.
  4. Create FlexTronScriptIncludes.html — this is for FlexTron only. DataFlex 26.0 can add JS dependencies to FlexTron applications automatically. This requires a new FlexTronScriptIncludes.html file that can be created by selecting this option. This new file is included to your application at compile time, so no deployment step is needed (unlike the web's index.html). You may preview the contents of this file by clicking on the Preview link.
  5. Adjust WebApp.src — This adjusts your project's precompiled header to use the new name of the Web packages. If you use precompiled headers in other source files as well, update those manually. You may be able to remove them altogether, but we recommend testing your project to verify that. You may preview the changes that will be applied to this file by clicking on the Preview link.

3. Compile and Run

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

You can compile from the Studio as before, or from the command line with df-cli. Use df-cli build — it builds a workspace and the targets bound to it, resolving the dependency tree and makepath for you (df-cli build "Order Entry.sws" --target "Order.src" --toolchain windows-64). df-cli build-file is the equivalent of the old dfcompconsole and is not recommended unless you know what you are doing; its main use is precompiling a header before building the targets.

If your application uses DataFlex standard About dialogs and image, you may see link errors related to the DacAbout.bmp file. DacAbout.bmp has been replaced by DataFlexAbout.bmp as part of reviewing our standard About dialog. If your project uses our standard About dialog, you may need to rescan images for the project so DacAbout.bmp gets replaced with DataFlexAbout.bmp in the project's CFG file. To do that in the Studio, open your project and select Project | Project Properties | Bitmaps tab and click on Scan for images…

If you get other 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 they should be minimal.

In some cases, 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 numerous libraries, the makepath may have worked only because the declaration order happened to be right — not because it matched the actual dependency tree. Now in 26.0 dependencies must be reviewed.

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, DataFlex 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 previous versions of DataFlex and the projects created using them.

4. Post-Migration

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

  • Uninstall or unlink your local packages (previously referred to as local libraries) one at a time and install the server-provided versions instead. This gives you updates and other capabilities over time. Do this at your own pace.
  • If you have libraries (now called "packages" when shared externally) that could be useful to others and are not yet available, consider pushing them to the DataFlex.dev server to share them with a wider DataFlex community of developers.

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