Indexed Property Design
Indexed properties allow array-like access to groups of items (for example, the characters in a string or the bits in a BitArray). Indexed properties, called indexers or default properties, differ from regular properties in that they take parameters indicating which element in the group to access. The implementation of an index property should be as simple as possible because indexers are often used in loops. The following guidelines help ensure that your types contain well-designed indexes where appropriate.
If an indexer requires multiple parameters, reevaluate whether the property really represents access to a logical collection. If not, use methods instead and consider choosing a method name that begins with Get
or Set
.
Avoid indexers with parameter types other than System.Int32, System.Int64, System.String, System.Object, enumerations, or generic type parameters.
If the design requires other types of parameters, you should strongly reevaluate whether the member really represents access to a logical collection. If not, use methods instead and consider choosing a method name that begins with Get
or Set
.
Do use the name Item for indexed properties unless there is an obviously better name (for example, see the System.String.Chars(System.Int32) property).
The IndexerNameAttribute attribute can be used to customize the name of an indexer.
In the following code example, the indexer should be changed to a method.
<System.Runtime.CompilerServices.IndexerNameAttribute("PositionsHeld")> _
Public Property Item (skillId as Integer) as JobInfoCollection
...
Public Function GetPositions(skillId as Integer, _
minJobLevel as Integer) _
as JobInfoCollection
[System.Runtime.CompilerServices.IndexerNameAttribute("PositionsHeld")]
public JobInfoCollection this [int skillId]
...
public JobInfoCollection GetPositions(int skillId, int minJobLevel)
Some compilers, such as the C# compiler, enforce this guideline.
Multiple sets of indexers are not supported by some languages. If you use them, some developers will not be able to access these members.
Some compilers, such as the C# compiler, enforce this guideline. Non-default indexed properties are not supported in all programming languages. If you use them, some developers will not be able to access these members.
Portions Copyright 2005 Microsoft Corporation. All rights reserved.
Portions Copyright Addison-Wesley Corporation. All rights reserved.
For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.
Member Design Guidelines
Design Guidelines for Developing Class Libraries