Before you go running off to start using ControlState, only to find out that it does not work, I should tell you that controls that use it must register themselves as needing it. This is accomplished by overriding the OnInit event of the control and calling the RegisterRequiresControlState method of the Page object, like so:

    Protected Overrides Sub OnInit(ByVal e As System.EventArgs)
        MyBase.OnInit(e)
        Page.RegisterRequiresControlState(Me)
    End Sub

That's it! All other aspects of ControlState work just like its cousin, ViewState. In fact, storage happens the same way too; ControlState is stored in a new hidden text field called __ControlState.

ControlState in Action

The sample webcontrol in the downloadable code displays a very simple (and pretty useless) form with two labels and two textboxes. We have a caption and textbox for 'first name' and a caption and textbox for 'last name'. I set up two properties for the label captions, appropriately called FirstNameCaption and LastNameCaption (sound familiar?).

    Protected _FirstNameCaption As String = "First name:"

    Public Property FirstNameCaption() As String
        Get
            Return _FirstNameCaption
        End Get
        Set(ByVal value As String)
            _FirstNameCaption = value
            Me.ChildControlsCreated = False
        End Set
    End Property

    Public Property LastNameCaption() As String
        Get
            If CType(ViewState("LastNameCaption"), Object) Is Nothing Then
                Return "Last name:"
            End If
            Return CType(ViewState("LastNameCaption"), String)
        End Get
        Set(ByVal Value As String)
            ViewState("LastNameCaption") = Value
            Me.ChildControlsCreated = False
        End Set
    End Property

The LastNameCaption property uses the conventional method of persistence using the now-all-too-familiar ViewState variable. However, the FirstNameCaption property exposes a member variable called _FirstNameCaption, which, unless we write some additional code, is not persisted.

As you can probably guess by now, I override the SaveControlState and LoadControlState methods to persist this variable.

    Protected Overrides Function SaveControlState() As Object
        Dim state() As Object = New Object(2) {}
        state(0) = MyBase.SaveControlState()
        state(1) = _FirstNameCaption
        Return state
    End Function

    Protected Overrides Sub LoadControlState(ByVal savedState As Object)
        If savedState IsNot Nothing Then
            Dim state() As Object = CType(savedState, Object())
            MyBase.LoadControlState(state(0))
            _FirstNameCaption = CType(state(1), String)
        End If
    End Sub

To test what I've done, I set up a sample web site that uses this control (also included in the downloadable code). On a webform, I drop an instance of our control, as well as two other buttons. The first button is labeled "Change Values," and the second, "Perform Postback."

In the Click event of the first button, I place the following code:

TestControl1.FirstNameCaption = "Enter your first name:"
TestControl1.LastNameCaption = "Enter your last name:"