You can maintain existing WinForms solutions that use legacy handles, but you should use declarative ViewModels for new user-interface work.

What legacy handles are

Legacy handles are design-time components used to place data access and expressions directly on a form or an EcoSpace design surface. Examples include ExpressionHandle, ReferenceHandle, CursorHandle, and VariableHandle.

Before declarative ViewModels, handles were the primary way to bring model data into a view. For example, a WinForms form could contain an ExpressionHandle whose expression supplies a value to a bound control.

Handles are still available in relevant Visual Studio designers, including the WinForms form designer and EcoSpace designer. Keep them when you are maintaining an established application that already depends on them. Do not choose them for new screens when a ViewModel can express the same requirement.

Prefer ViewModels for new work

A ViewModel is the declarative way to define what a view needs from the model. Compared with placing individual handles on a designer surface, ViewModels provide better maintenance, efficient fetching, type checking, and tracking of element usage.

For example, when a form needs a customer and values derived from that customer, define the required data and expressions in its ViewModel rather than adding several handles to the form. This keeps the view's data requirements in one declarative definition instead of distributing them across design-time components.

For WinForms projects, see Documentation:WinForms MDrivenFramework for the supported approaches, including using standard WinForms binding with MDriven handles and mixing handles with declarative ViewModels. When you use ViewModels at runtime, initialize them as required by that approach.

Maintain existing handle-based forms

Use this process when you need to edit or troubleshoot a form that already contains handles.

1. Open the relevant form or EcoSpace designer in Visual Studio.
2. Locate the existing handle in the designer or its generated design-time setup. Do not replace it during unrelated maintenance unless you also move the consuming view logic to a ViewModel.
3. Check the handle expression before changing it. Handle expressions are validated as OCL columns in current framework behavior; invalid OCL can fail during derivation even if a particular column is not visibly used.
4. If an existing VariableHandle expression relies on self, review the changed defaults for AddDefaultNestings and AddDefaultProperties. When the intent is to expose the current object, use AddSelfColumn on the VariableHandle instead of relying on those defaults.
5. Rebuild the solution after changing a handle expression or its supporting model code.

For behavior changes affecting OCL columns, self, and VariableHandle defaults, see Documentation:Breaking changes.

Resolve handle designer version errors

When configuring a legacy handle or editing its expression, Visual Studio can report an error similar to:

You have version x of the MDrivenFramework installed, but version y on the assemblies in the solution.

This means the MDriven extension and the assemblies referenced by the solution are not aligned, or Visual Studio has loaded handle assemblies from conflicting locations. The conflict historically involved Eco.Handles.dll: the Visual Studio extension could load one copy while the designer loaded another copy from Visual Studio's project-assembly cache. That can produce misleading type or missing-method errors, such as an ExpressionHandle not converting to an ElementHandle.

Check versions first

Follow these steps before attempting any cache or GAC-related remediation.

1. Identify the version of the installed MDriven Visual Studio extension.
2. Check the MDriven and, where applicable, legacy Eco NuGet package versions referenced by the solution.
3. Update the solution packages so that they use the version expected by the installed extension.
4. Rebuild the complete solution.
5. Close and reopen the affected designer, then retry the handle or expression edit.

The extension version and project packages must be compatible because design-time behavior and the compiled application can otherwise execute different handle assembly versions.

Apply the package rule for your target framework

For projects targeting .NET 6 or later, use MDriven packages and do not mix in old Eco* packages. For projects targeting .NET Framework 4.7.2 through 4.8, the package mix described in Documentation:MDriven 7.2 applies: use the specified MDriven .NET Standard packages, while legacy assemblies may still be used for areas such as WinForms, WPF, and HTTP.

Project target	Handle/package guidance
.NET 6 or later	Use MDriven.* packages; do not include old Eco* packages.
.NET Framework 4.7.2 to 4.8	Follow the mixed-package guidance in Documentation:MDriven 7.2 for the required MDriven .NET Standard and legacy framework-specific assemblies.

Do not use old GAC advice as a default fix

Older Visual Studio design-time scenarios used the Global Assembly Cache (GAC) to force Visual Studio to load the intended Eco.Handles.dll before a project-cached copy. This also meant that a GAC assembly could override the version in an application's bin directory. GAC installation and removal were therefore version-sensitive operations, not general cleanup steps.

MDriven 7.2 changed the handle design-time approach so the GAC is no longer required. Handle data is serialized and transferred between design-time types, including across the process boundary used by the .NET 6+ WinForms designer. Do not manually delete Eco.*, MDriven.*, or WECPOFLogic folders from the GAC as routine troubleshooting for a current installation.

If you maintain an older solution and have already established that it depends on the historical GAC workaround, follow the specific procedure in Documentation:Before going nuts about this issue. That page explains the underlying assembly-load conflict and the version constraint that applies when GAC is involved.

Diagnose by symptom

Symptom	Likely area to check	Next action
Framework/assembly versions reported as different	Extension and NuGet package alignment	Compare the installed MDriven extension with the solution's package versions, update the solution packages as needed, and rebuild.
A handle type cannot be converted to another handle type	Two handle assembly copies loaded by Visual Studio design time	Read Documentation:Before going nuts about this issue and verify whether the project is using the historical WinForms designer scenario described there.
A handle-related method is reported as missing	Mixed or incompatible design-time and project assemblies	Check package target-framework rules in Documentation:MDriven 7.2, then align packages and rebuild.
A changed OCL column or expression fails during derivation	Invalid OCL or changed legacy expression behavior	Correct the expression and review Documentation:Breaking changes.

Modernize deliberately

Do not convert a handle-based screen by replacing components one at a time without checking how bindings, expressions, and runtime initialization work together. Treat the conversion as a view-level change: identify the data the screen needs, define that data in a ViewModel, update the bindings, and test the screen's loading and actions.

If the application was created from, or is being adapted to, an existing database, keep database-reversal and persistence-mapping work separate from the UI modernization. See Documentation:Making sense of legacy data–DB Reverse for legacy database work and Documentation:Using other than standard Persistence Mappers per attribute when mappings need attribute-level configuration.

See also

• Documentation:WinForms MDrivenFramework
• Documentation:MDriven 7.2
• Documentation:Before going nuts about this issue
• Documentation:Breaking changes
• Documentation:VS2026 is now supported - what we changed and what we learned

Scope: legacy UI handles, not database migration

You can use this page to maintain or replace older MDriven WinForms handle-based UI binding; it is for developers working with existing MDriven forms, not for importing an external legacy application or database.

In this page, legacy handles means the pre-ViewModel design-time components used to bring model data and expressions into a view, such as ExpressionHandle, ReferenceHandle, CursorHandle, and VariableHandle.

For example, if an existing WinForms form has an ExpressionHandle bound to a control, use this page to maintain that form or move its data requirement into a ViewModel. If you are connecting MDrivenServer to an existing database or moving an existing ECO application to MDrivenServer, use Documentation:Moving from legacy ECO to MDrivenServer. If you are examining legacy database data, see Documentation:Making sense of legacy data–DB Reverse.