Edit

Key (Visual Basic)

  • Article

The Key keyword enables you to specify behavior for properties of anonymous types. Only properties you designate as key properties participate in tests of equality between anonymous type instances, or calculation of hash code values. The values of key properties cannot be changed.

You designate a property of an anonymous type as a key property by placing the keyword Key in front of its declaration in the initialization list. In the following example, Airline and FlightNo are key properties, but Gate is not.

Dim flight1 = New With {Key .Airline = "Blue Yonder Airlines",
                        Key .FlightNo = 3554, .Gate = "C33"}

When a new anonymous type is created, it inherits directly from Object. The compiler overrides three inherited members: Equals, GetHashCode, and ToString. The override code that is produced for Equals and GetHashCode is based on key properties. If there are no key properties in the type, GetHashCode and Equals are not overridden.

Equality

Two anonymous type instances are equal if they are instances of the same type and if the values of their key properties are equal. In the following examples, flight2 is equal to flight1 from the previous example because they are instances of the same anonymous type and they have matching values for their key properties. However, flight3 is not equal to flight1 because it has a different value for a key property, FlightNo. Instance flight4 is not the same type as flight1 because they designate different properties as key properties.

Dim flight2 = New With {Key .Airline = "Blue Yonder Airlines",
                        Key .FlightNo = 3554, .Gate = "D14"}
' The following statement displays True. The values of the non-key 
' property, Gate, do not have to be equal.
Console.WriteLine(flight1.Equals(flight2))

Dim flight3 = New With {Key .Airline = "Blue Yonder Airlines",
                        Key .FlightNo = 431, .Gate = "C33"}
' The following statement displays False, because flight3 has a
' different value for key property FlightNo.
Console.WriteLine(flight1.Equals(flight3))

Dim flight4 = New With {Key .Airline = "Blue Yonder Airlines",
                        .FlightNo = 3554, .Gate = "C33"}
' The following statement displays False. Instance flight4 is not the 
' same type as flight1 because they have different key properties. 
' FlightNo is a key property of flight1 but not of flight4.
Console.WriteLine(flight1.Equals(flight4))

If two instances are declared with only non-key properties, identical in name, type, order, and value, the two instances are not equal. An instance without key properties is equal only to itself.

For more information about the conditions under which two anonymous type instances are instances of the same anonymous type, see Anonymous Types.

Hash Code Calculation

Like Equals, the hash function that is defined in GetHashCode for an anonymous type is based on the key properties of the type. The following examples show the interaction between key properties and hash code values.

Instances of an anonymous type that have the same values for all key properties have the same hash code value, even if non-key properties do not have matching values. The following statement returns True.

Console.WriteLine(flight1.GetHashCode = flight2.GetHashCode)

Instances of an anonymous type that have different values for one or more key properties have different hash code values. The following statement returns False.

Console.WriteLine(flight1.GetHashCode = flight3.GetHashCode)

Instances of anonymous types that designate different properties as key properties are not instances of the same type. They have different hash code values even when the names and values of all properties are the same. The following statement returns False.

Console.WriteLine(flight1.GetHashCode = flight4.GetHashCode)

Read-Only Values

The values of key properties cannot be changed. For example, in flight1 in the earlier examples, the Airline and FlightNo fields are read-only, but Gate can be changed.

' The following statement will not compile, because FlightNo is a key
' property and cannot be changed.
' flight1.FlightNo = 1234
'
' Gate is not a key property. Its value can be changed.
flight1.Gate = "C5"

See also