Skip to content

Update AggregateException.xml #10396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 24, 2024
Merged

Update AggregateException.xml #10396

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d6d7e9
Update AggregateException.xml
epsitec Sep 13, 2024
4f513d6
Update xml/System/AggregateException.xml
epsitec Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions xml/System/AggregateException.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -682,8 +682,8 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>Returns the <see cref="T:System.AggregateException" /> that is the root cause of this exception.</summary>
<returns>The <see cref="T:System.AggregateException" /> that is the root cause of this exception.</returns>
<summary>Returns the <see cref="T:System.Exception"/> that is the root cause of this exception. This exception is either the root exception or the first <see cref="T:System.AggregateException"/> that contains either multiple inner exceptions or no inner exceptions at all.</summary>
<returns>The <see cref="T:System.Exception" /> that is the root cause of this exception.</returns>
Comment on lines +685 to +686
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<summary>Returns the <see cref="T:System.Exception"/> that is the root cause of this exception. This exception is either the root exception or the first <see cref="T:System.AggregateException"/> that contains either multiple inner exceptions or no inner exceptions at all.</summary>
<returns>The <see cref="T:System.Exception" /> that is the root cause of this exception.</returns>
<summary>Returns the <see cref="T:System.AggregateException"/> that is the root cause of this exception. This exception is either the current exception or the first <see cref="T:System.AggregateException"/> that contains either multiple inner exceptions or no inner exceptions at all.</summary>
<returns>The <see cref="T:System.AggregateException" /> that is the root cause of this exception.</returns>

https://learn.microsoft.com/en-us/dotnet/api/system.exception.getbaseexception and other docs use "current exception" for this.

Also, I think the original docs were better in highlighting that the returned instance is always AggregateException.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original docs were wrong, hence my fixes. The code will return the plain Exception which was thrown up the chain (what's now called the current exception), and only if there are multiple exceptions wrapped in an AggregateException will it return an aggregate exception. That's the whole point of this pull request.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok, I have misread how the implementation behaves.

I agree with you that the return type in the docs is wrong.

I am not sure whether it makes sense to try to describe the exact algorithm used by this method in the docs. The current implementation of Exception.GetBaseException and AggregateException.GetBaseException methods are in conflict with the contract for these methods described in the docs.

https://learn.microsoft.com/en-us/dotnet/api/system.exception.getbaseexception?view=net-8.0 says "For all exceptions in a chain of exceptions, the GetBaseException method must return the same object (the base exception).". For example, this invariant does not seem to hold for

TargetInvocationException 
   -> AggregateException
          -> ArgumentException
          -> ArgumentException

GetBaseException() called on TargetInvocationException returns first ArgumentException for , but GetBaseException() called on AggregateException returns the same AggregateException.

We may want to fix the implementation and/or docs to make this more sensible.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, practically, are you @jkotas addressing this in the documentation?

<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down