Previous | Index | Next 

[PRB] Property references in a form might not match property names in a UserControl

A VB6 UserControl stores its own properties in the PropertyBag object, so that the design-time value of such properties is preserved in .frm and .frx files. This action is carried out in the WriteProperties event, as in this example:

        Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
            PropBag.WriteProperty("Caption" , Me.Caption)
            PropBag.WriteProperty("Value" , Me.Value)
        End Sub

The ActiveX Control Interface Wizard generates a series of WriteProperty calls, one for each property that the control exposes; the string value passed in the first argument is equal to the name of the property.

An undocumented detail of the PropertyBag object is that the name that you pass in the first argument of the WriteProperty method is the property name used inside the (hidden) portion of the .frm file where design-time values are stored. This means that, if you don’t use the ActiveX Control Interface Wizard to generate the code inside the WriteProperties event handler, then the name of the property as found in the .frm file doesn’t necessarily match the name of the property as exposed by the user control. For example, if you have the following WriteProperties handler:

        Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
            PropBag.WriteProperty("CAP" , Me.Caption)
            PropBag.WriteProperty("VAL" , Me.Value)
        End Sub

then design-time values for the Caption and Value properties will appear in the .frm file as references to the CAP and VAL properties, but these properties don’t exist. All such references cause a compilation error in the converted VB.NET application.

You can’t work around this issue by editing all WriteProperty and ReadProperty methods in the user control, because doing so would prevent VB6 from reading all .frm files that contain a reference to the user control. However, you can teach VB Migration Partner that the names used in the PropertyBag differ from the public names of properties, You do so by means of a TranslateProperties pragma located at the top of the UserControl class. Here’s the right pragma to account for the previous case:

        '## TranslateProperties "CAP=Caption,VAL=Value"

This pragma works correctly both for private user controls contained in the current project and for user controls defined in a separate ActiveX Control project. In both cases the pragma causes the following attribute to be created at the top of the UserControl class:

        <VB6Object("SampleProject.SampleUserControl", _
            TranslateProperties:="CAP=Caption,VAL=Value")> _
        Public Class SampleUserControl
        End Class

The TranslateProperties value in the VB6Object attribute ensures that the CAP and VAL properties are correctly interpreted if you compile the converted VB.NET project and make the resulting DLL available to VB Migration Partner.


Previous | Index | Next