This documentation is archived and is not being maintained.

Collections in Visual Basic .NET

In general terms, a collection is a way of grouping and managing related objects. This simple definition, however, describes a somewhat complex reality.

Every form, for example, has a Controls collection. This is an object that represents all the controls on that form. It allows you to obtain a reference to a control in the collection by its index, and to loop through the members of the collection using For Each...Next statements.

Visual Basic also provides a Collection class, with which you can define and create your own collections. Like a form's Controls collection, the Collection class also provides you with the built-in functionality to loop through members using For Each...Next and to reference members by index. Since both are collections, why then does the following code from a Windows Forms application generate a compiler error?

Dim myControlsCollection As Collection
myControlsCollection = Controls   ' This line generates a compiler error.

What's happening here? The Controls collection is a collection; the variable myControlsCollection is declared as Collection; why can't you assign a reference to Controls to the variable myControlsCollection?

The reason is that the Collection class and the Controls collection are not polymorphic; that is, they aren't interchangeable, because they are different types with different implementations. They don't have the same methods, store object references in the same way, or use the same kinds of index values.

These differences make the Collection class's name seem like an odd choice, because it really represents only one of many possible collection implementations. This topic explores some of these implementation differences.

Zero-Based and One-Based Collections

A collection is either zero-based or one-based, depending on what its starting index is. As you might guess, the former means that the index of the first item in the collection is zero, and the latter means that it is one. An example of a zero-based collection is the Controls collection, discussed above. An instance of the Collection object, also discussed above, is an example of a one-based collection.

One-based collections are more intuitive to use, because the index ranges from one to Count, where the Count property returns the number of items in a collection. The index of a zero-based collection, by contrast, ranges from zero to one less than the Count property.

The .NET Framework is standardizing collection as being zero-based. The Visual Basic Collection class is one based primarily for the purpose of compatibility with previous versions.

Index and Key Values

Many collections in Visual Basic allow you to access an item using either a numeric index or a String key, as do instances of the Visual Basic Collection class. You may also add items to Collection objects without specifying a key.

By contrast, some collections (such as System.Collections.ArrayList) allow only a numeric index. These collections provide access to their members only through the index, and do not allow you to associate a key.

Adding and Removing Items

Collections also differ in whether or not you can add items to them, and if so, how those items are added. Because the Visual Basic Collection object is a general-purpose programming tool, it's more flexible than other collections. It has an Add method for putting items into the collection, and a Remove method for taking items out.

Certain specialized collections, on the other hand, do not allow developers to add and remove members using code. For example, the CheckedListBox.CheckedItems property returns references to items by index, but you cannot add and remove items from the collection in code. Rather you can only do so by checking or unchecking the appropriate box in the visual interface. Thus there is no Add or Remove method for this collection.

See Also

Walkthrough: Creating Your Own Collection Class | Collections in Visual Basic .NET | Creating Collections of Objects | The Visual Basic .NET Collection Class | For Each...Next Statements | Count Property | Add Method | Remove Method | CheckedListBox.CheckedItems Property