Property Procedures (Visual Basic)

A property procedure is a series of Visual Basic statements that manipulate a custom property on a module, class, or structure. Property procedures are also known as property accessors.

Visual Basic provides for the following property procedures:

• A Get procedure returns the value of a property. It is called when you access the property in an expression.

• A Set procedure sets a property to a value, including an object reference. It is called when you assign a value to the property.

You usually define property procedures in pairs, using the Get and Set statements, but you can define either procedure alone if the property is read-only (Get Statement) or write-only (Set Statement (Visual Basic)).

You can omit the Get and Set procedure when using an auto-implemented property. For more information, see Auto-Implemented Properties (Visual Basic).

You can define properties in classes, structures, and modules. Properties are Public by default, which means you can call them from anywhere in your application that can access the property's container.

For a comparison of properties and variables, see Differences Between Properties and Variables in Visual Basic.

Declaration Syntax

A property itself is defined by a block of code enclosed within the Property Statement and the End Property statement. Inside this block, each property procedure appears as an internal block enclosed within a declaration statement (Get or Set) and the matching End declaration.

The syntax for declaring a property and its procedures is as follows:

[Default] [Modifiers] Property PropertyName[(ParameterList)] [As DataType]
    [AccessLevel] Get
        ' Statements of the Get procedure.
        ' The following statement returns an expression as the property's value.
        Return Expression
    End Get
    [AccessLevel] Set[(ByVal NewValue As DataType)]
        ' Statements of the Set procedure.
        ' The following statement assigns newvalue as the property's value.
        LValue = NewValue
    End Set
End Property
- or -
[Default] [Modifiers] Property PropertyName [(ParameterList)] [As DataType]

The Modifiers can specify access level and information regarding overloading, overriding, sharing, and shadowing, as well as whether the property is read-only or write-only. The AccessLevel on the Get or Set procedure can be any level that is more restrictive than the access level specified for the property itself. For more information, see Property Statement.

Data Type

A property's data type and principal access level are defined in the Property statement, not in the property procedures. A property can have only one data type. For example, you cannot define a property to store a Decimal value but retrieve a Double value.

Access Level

However, you can define a principal access level for a property and further restrict the access level in one of its property procedures. For example, you can define a Public property and then define a Private Set procedure. The Get procedure remains Public. You can change the access level in only one of a property's procedures, and you can only make it more restrictive than the principal access level. For more information, see How to: Declare a Property with Mixed Access Levels (Visual Basic).

Parameter Declaration

You declare each parameter the same way you do for Sub Procedures (Visual Basic), except that the passing mechanism must be ByVal.

The syntax for each parameter in the parameter list is as follows:

[Optional] ByVal [ParamArray] parametername As datatype

If the parameter is optional, you must also supply a default value as part of its declaration. The syntax for specifying a default value is as follows:

Optional ByVal parametername As datatype = defaultvalue

Property Value

In a Get procedure, the return value is supplied to the calling expression as the value of the property.

In a Set procedure, the new property value is passed to the parameter of the Set statement. If you explicitly declare a parameter, you must declare it with the same data type as the property. If you do not declare a parameter, the compiler uses the implicit parameter Value to represent the new value to be assigned to the property.

Calling Syntax

You invoke a property procedure implicitly by making reference to the property. You use the name of the property the same way you would use the name of a variable, except that you must provide values for all arguments that are not optional, and you must enclose the argument list in parentheses. If no arguments are supplied, you can optionally omit the parentheses.

The syntax for an implicit call to a Set procedure is as follows:

propertyname[(argumentlist)] = expression

The syntax for an implicit call to a Get procedure is as follows:

lvalue = propertyname[(argumentlist)]

Do While (propertyname[(argumentlist)] > expression)

Illustration of Declaration and Call

The following property stores a full name as two constituent names, the first name and the last name. When the calling code reads fullName, the Get procedure combines the two constituent names and returns the full name. When the calling code assigns a new full name, the Set procedure attempts to break it into two constituent names. If it does not find a space, it stores it all as the first name.

Dim firstName, lastName As String 
Property fullName() As String 
    Get 
      If lastName = "" Then 
          Return firstName
      Else 
          Return firstName & " " & lastName
      End If 

    End Get 
    Set(ByVal Value As String)
        Dim space As Integer = Value.IndexOf(" ")
        If space < 0 Then
            firstName = Value
            lastName = "" 
        Else
            firstName = Value.Substring(0, space)
            lastName = Value.Substring(space + 1)
        End If 
    End Set 
End Property

The following example shows typical calls to the property procedures of fullName.

fullName = "MyFirstName MyLastName"
MsgBox(fullName)

See Also

Tasks

How to: Create a Property (Visual Basic)

How to: Call a Property Procedure (Visual Basic)

How to: Declare and Call a Default Property in Visual Basic

How to: Put a Value in a Property (Visual Basic)

How to: Get a Value from a Property (Visual Basic)

Concepts

Procedures in Visual Basic

Function Procedures (Visual Basic)

Operator Procedures (Visual Basic)

Procedure Parameters and Arguments (Visual Basic)

Differences Between Properties and Variables in Visual Basic