Clarify that reflection member enumeration order is not guaranteed

[Copilot]

Reflection APIs like Type.GetMethods() currently appear to group members by inheritance depth, but that behavior is an implementation detail rather than a contract. This change makes the API docs explicit that callers should not depend on ordering across inherited members.

• Description

  • Added XML docs to the array-returning reflection APIs on System.Type that are commonly used for member enumeration:
    • GetEvents
    • GetFields
    • GetMember(string)
    • GetMembers
    • GetMethods
    • GetProperties
  • Documented that the returned arrays are not guaranteed to be ordered in any particular way, including:
    • alphabetical order
    • declaration order
    • inheritance-hierarchy order

• Effect on callers

  • The docs now make it clear that code like the following should not assume derived-type members always precede base-type members:

foreach (MethodInfo method in typeof(Derived).GetMethods())
{
    Console.WriteLine($"{method.DeclaringType}.{method.Name}");
}

• Scope
  • Documentation-only update; no runtime behavior changes are intended.

[jkotas]

This repo is not the source of truth for the documentation of these APIs.

The official documentation documents this already. From https://learn.microsoft.com/en-us/dotnet/api/system.type.getevents :

In .NET 6 and earlier versions, the GetEvents method does not return events in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which events are returned, because that order varies. However, starting with .NET 7, the ordering is deterministic based upon the metadata ordering in the assembly.

[jkotas]

Reflection APIs like Type.GetMethods() currently appear to group members by inheritance depth, but that behavior is an implementation detail rather than a contract

I am not sure we want to make this guarantee. I think it would just encourage using reflection APIs in a fragile way.

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @dotnet/area-system-reflection
See info in area-owners.md if you want to be subscribed.

[steveisok]

This repo is not the source of truth for the documentation of these APIs.

The official documentation documents this already. From https://learn.microsoft.com/en-us/dotnet/api/system.type.getevents :

In .NET 6 and earlier versions, the GetEvents method does not return events in a particular order, such as alphabetical or declaration order. Your code must not depend on the order in which events are returned, because that order varies. However, starting with .NET 7, the ordering is deterministic based upon the metadata ordering in the assembly.

Thanks - should have looked there first ;-).