Support Statement: using specializedHookup="on" when migrating event handlers

Owned by Mark Juras
Last updated: Aug 22, 2023

The 08/21/2023 version of gmStudio changes how control events are hooked to handlers in designer code.

Prior to the 5/30/2023 release, all events hookup used the specialized delegate form:

this.tvTreeView.NodeMouseClick += new System.Windows.Forms.TreeNodeMouseClickEventHandler(this.tvTreeView_NodeClick);

In the last release (5/30/2023), all events hookup here modified to use the simplified form:

this.tvTreeView.NodeMouseClick += this.tvTreeView_NodeClick;

The simplified form was introduced as part of the event handler enhancements implemented with the 5/30 release.  It was selected because it supports both specialized delegates and generic delegates.  However, when one modifies and saves a form in the Visual Studio designer, all of the simplified event handler hookups were removed from the rewritten form!  This makes the form non-functional.  In order for the hookups to be retained by the VS Designer rewriting process, a generic or specialized delegate must be used. 

If you are migrating to a stub control generated by the tool (e.g. the default) then the event will have a generic delegate and no action is needed.  However, if you are migrating to a .NET control (e.g. a WinForms control) then it is likely that the event will require the more traditional specialized delegate form.  This must be specified in the migration rules using a specializedHookup=on attribute in the migration rules for the event, for example:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
C:\gmTestBed\FileExplorer\proj_csh\usr\Mscomctl.ocx.WinForms.Refactor.xml
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 266    <Migrate id="ITreeViewEvents.NodeClick" migName="NodeMouseClick" SpecializedHookup="on" netHandler="System.Windows.Forms.TreeNodeMouseClickEventHandler" netArgs="TreeNodeMouseClickEventArgs" />


Failing to specify this attribute when migrating MSCOMCTL to WinForms, will result in a build error:

ERRNUM: CS0029: Cannot implicitly convert type 'System.EventHandler<System.Windows.Forms.TreeNodeMouseClickEventArgs>' to 'System.Windows.Forms.TreeNodeMouseClickEventHandler'
NETSRC: C:\gmTestBed\FileExplorer\proj_csh\deploy\FileExplorer\frmExploreLite.Designer.cs@318 : InitializeComponent
    this.tvTreeView.NodeMouseClick += new System.EventHandler<TreeNodeMouseClickEventArgs>(this.tvTreeView_NodeClick);

Similar issues are likely to occur with other controls that use specialized delegate events.

We regret this detail was missed when testing the changes for generic events; testing for designer rewrite problems will be standard operating procedure going forward.

The easiest way to correct this is by editing the migration rules files adding specializedHookup="on".  Most of these can be picked up using a search-replace

Old: netHandler="
New: specializedHookup="on"  netHandler="

Some of the sample rules distributed with gmStudio have been updated to reflect this requirement.


NOTE: The WinForms Designer for .NET Core supports simplified handler hookups.  We will consider this in the upcoming .NET Core feature planned for late 2023.

Please let us know if you have questions or require assistance.