You can build a Windows Forms client against an MDriven model by using legacy Handles or declarative ViewModels; this page helps WinForms developers choose the right approach and start from the MDriven Framework solution template.

Choose an integration approach

MDriven Framework WinForms applications can present model data in two ways:

Approach	Use it when	Guidance
Handles	You maintain an existing WinForms application that already binds controls to Handles.	Handles remain available, but they are legacy technology. Do not choose them for new UI work.
Declarative ViewModels	You create new WinForms UI or move an existing UI toward a model-defined presentation layer.	Use this approach for new work. ViewModels provide maintenance, efficient fetch, type checking, and element-usage tracking benefits over Handles.

A ViewModel defines the data and interaction shape that a view consumes. For example, a customer-editing ViewModel can expose a customer name, a list of orders, and actions that the user can invoke. Your WinForms controls then display and edit the ViewModel's runtime data rather than each control independently constructing its own model query.

Prerequisites

Before creating or opening a WinForms project:

1. Install Visual Studio 2022.
2. Download and install MDriven Framework, including the Visual Studio 2022 VSIX, as described in Documentation:MDrivenFramework.
3. Create an MDriven solution from the MDriven Solution Template.
4. Update the solution's ECO/MDriven NuGet packages to the current version used by your installed MDriven tooling.
5. Build the solution before editing the WinForms UI.

The solution template can contain several projects. Keep the projects that match the application targets you need. The template is also a useful reference when you need to restore a known working project structure.

Start a WinForms client from the solution template

Use the generated WinForms project as the starting point for the same model used by other client projects in the solution.

1. Open the model in MDriven Designer.
2. Add or change classes, attributes, associations, and ViewModels as required.
3. Generate code from the model.
4. Build the solution.
5. Select the WinForms project as the startup project and run it.

The MDriven Framework template is intended to let you run WinForms and WPF projects against the same model, including Framework 4.7.2 and .NET 8 targets where those projects are present. For the complete template setup and target overview, see Documentation:MDrivenFramework.

Use declarative ViewModels for new WinForms UI

For a new screen, define the presentation structure in a declarative ViewModel and connect the WinForms UI to its runtime instance.

1. In MDriven Designer, create or update the declarative ViewModel that represents the screen.
2. Add the elements that the screen must display or edit. For example, a customer screen can include a selected customer, the customer's name, and a collection of that customer's orders.
3. Generate code and rebuild the solution.
4. In the WinForms application startup or screen setup code, initialize the ViewModel at runtime before controls use it.
5. Bind or connect the WinForms controls to the initialized ViewModel runtime data.
6. Run the application and verify that the ViewModel retrieves the expected data and that actions operate in the intended context.

Important: defining a ViewModel in the model does not by itself create a runtime instance for a WinForms screen. Initialize the ViewModel in runtime before the UI attempts to read its values, collections, or actions. If a screen is bound before initialization, it has no initialized ViewModel context to present.

Keep the ViewModel focused on the screen's needs. For example, use one ViewModel for a customer list and another for customer detail when the two screens need different data, commands, or selection context.

For the broader ViewModel vocabulary and related concepts, see Education:TheIndex.

Maintain an existing Handles-based WinForms UI

Handles were the original way to bring MDriven data into views. In a legacy WinForms form, relevant Handles are available through the WinForms form designer and can be used to bind standard .NET Windows Forms controls.

Continue to use Handles when you are maintaining an existing form, but prefer declarative ViewModels when adding new screens. Do not mix a migration decision with unrelated form changes: keep the existing Handle binding working first, then move a screen to a ViewModel when you can test the complete screen behavior.

For Handle types, designer use, version mismatch errors, and legacy GAC cleanup, follow Documentation:Working with legacy Handles.

Resolve a Handle designer version mismatch

If the designer reports that the installed MDrivenFramework version differs from the assemblies in the solution:

1. Install or update the MDriven Framework tooling.
2. Update the ECO/MDriven NuGet packages in the solution so they use the same version as the installed Visual Studio VSIX.
3. Rebuild the solution.

Older Visual Studio installations can also leave legacy MDriven assemblies in the Global Assembly Cache (GAC). The detailed cleanup guidance, including the affected assembly folders, is maintained in Documentation:Working with legacy Handles.

WinForms designer compatibility

MDriven 7.2 includes a WinForms designer breaking change for generated code that adds columns to an expression handle. If generated designer code uses Eco.Handles.IColumn[], change that array type to Eco.Handles.AbstractColumn[].

expressionHandle1.Columns.AddRange(
    new Eco.Handles.AbstractColumn[] { oclColumn1, oclColumn2 });

Read Documentation:MDriven 7.2 before upgrading an existing solution, because it documents this and other framework changes.

When your WinForms application hosts WPF UI

A WinForms application can use WPF windows, such as the WPF runtime debugger. When the application's Application object is a WinForms application, WPF must be configured for this situation on a window-by-window basis. Keyboard interoperability is also needed for true WPF forms hosted in the WinForms environment.

Use the implementation guidance and code in Documentation:WPF Debugger rather than duplicating it in the WinForms project.

Development checklist

Before you commit a WinForms UI change, verify the following:

• The MDriven VSIX and the solution's ECO/MDriven NuGet packages use matching versions.
• You generated code after changing the model.
• The solution builds after generation.
• New screens use declarative ViewModels rather than new Handles.
• Every ViewModel-backed screen initializes its ViewModel runtime instance before binding or displaying ViewModel data.
• A legacy Handle screen still opens in the WinForms designer and at runtime after package updates.

See also

• Documentation:MDrivenFramework
• Documentation:Framework
• Documentation:Working with legacy Handles
• Documentation:MDriven 7.2
• Education:TheIndex