[Breaking change]: exceptions thrown by reflection Invoke() APIs have changed

[steveharter]

Description

The exceptions thrown when calling reflection invoke APIs have changed.

Version

.NET 7 Preview 4

Previous behavior

A ref-returning method that returns null threw NullReferenceException.

For constructors:

• Transient exceptions including OutOfMemoryException used to be thrown.
• A negative value for the length parameter of an array threw OverflowException.

When a null was passed for a byref-like parameter and is passed by-value (without the ref modifier) no exception was thrown and the runtime substituted a default value for the null value.

New behavior

Instead of the originating exception (including the NullReferenceException and OutOfMemoryException mentioned in the Previous Behavior), TargetInvocationException is now thrown for all reflection invoke cases after the initial Invoke() parameters are validated. The inner exception contains the originating exception.

NotSupportedException is thrown when a null is passed for a byref-like type parameter when the parameter is declared as being by-value (i.e. no ref modifier). Note that for the related case for when the parameter is by-reference (with the ref modifier), the previous and new behavior are the same: NotSupportedException is thrown.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

For the case where TargetInvocationException is now thrown instead of the originating exception, this makes the experience more consistent since it properly layers exceptions caused by the validation of the incoming parameters (which are not wrapped with TargetInvocationException) vs. any exception thrown due to the implementation of the target method (which are wrapped). Having consistent rules makes it more likely to have a consistent experience across different CLR implementations and across different implementations of Invoke APIs.

For the by-ref-like type case of now throwing NotSupportedException, the change fixes an oversight of the original implementation which did not throw and thus made it appear by-ref-like types are supported by the existing Invoke() APIs when they are not. Since the current Invoke() APIs use System.Object for parameter types, and a by-ref-like type cannot be boxed to System.Object, that is an unsupported scenario.

Recommended action

If BindingFlags.DoNotWrapExceptions is not used when calling Invoke() and there are catch statements around the Invoke() APIs for exceptions other than TargetInvocationException, consider changing or removing those catch statements since they will no longer be thrown. This assumes, however, that the exceptions being caught are thrown as a result of the invocation and not because of invalid parameters which are validated before attempting to invoke the target method. Invalid parameters which are validated before attempting to invoke are thrown without being wrapped with TargetInvocationException and did not change semantics.

Consider using BindingFlags.DoNotWrapExceptions so that TargetInvocationException is never thrown - the originating exception will not be wrapped by a TargetInvocationException. In most cases, this improves the chances of the diagnosing the actual issue since not all exception reporting tools will display the inner exception. In addition, by using BindingFlags.DoNotWrapExceptions, the same exceptions will be thrown as when calling the method directly (without reflection) which in most cases is most cases is desired since the choice of whether reflection is used or not can be arbitrary or an implementation detail that does not need to surface to the caller.

In the rare case of needing to pass a default value to a method through reflection that contains a byref-like type parameter when the parameter is declared as being by-value (i.e. no ref modifier), a wrapper method can be added that does not contain that parameter and calls the target method with the default value for that parameter.

Feature area

Core .NET libraries

Affected APIs

All overloads of

• System.Reflection.MethodInfo.Invoke()
• System.Reflection.ConstructorInfo.Invoke()
• System.Reflection.PropertyInfo.GetValue()
• System.Reflection.PropertyInfo.SetValue()
• System.Reflection.Emit.DynamicMethod.Invoke()

All overloads that contain the object?[]? args parameter:

• System.Activator.CreateInstance()