Add remarks to FromBodyAttrbiute

[voroninp]

Add remarks to FromBodyAttrbiute

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Summary of the changes (Less than 80 chars)

Description

[FromBody] attrbiute section of the docs dedicated to Model Binding contains a very important statement:

The ASP.NET Core runtime delegates the responsibility of reading the body to an input formatter.

This is quite an important detail (gotcha, actually) to capture it in the xmldoc of the attribute, so it's imediately visible in IDE.

[joegoldman2]

This is true for MVC but not for minimal API, which also uses the same attribute.

[voroninp]

How does it behave for minipal API then?

[martincostello]

I think it just reads the form itself directly before passing control to the user's endpoint method using https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.http.features.iformfeature.readformasync (I haven't dug through the code to check, but that's what I see to remember from doing work on the binding "glue" stuff).

[voroninp]

Found it:
Here and then here.

Ok, I need to change the wording. The fun thing that MVC's model binding involves validation, and even System.Text.Json does not care about [Required] attrbiute I get 400 Bad Request while for minimal API I get 200.

[voroninp]

@martincostello , I changed the wording.

[KennethHoff]

What exactly is "an input formatter"?

[voroninp]

@KennethHoff ,is it a hint that link to the description of formatters concept is missing or a real question?

If it's the latter one , then
https://learn.microsoft.com/en-us/aspnet/core/web-api/advanced/formatting?view=aspnetcore-8.0

[KennethHoff]

@KennethHoff ,is it a hint that link to the description of formatters concept is missing or a real question?

Both, really 😅

[captainsafia]

LGTM!

Out of curiousity, what motiviated you to add this note? It seems like you might not have expected input formatters to be coming in to play here?

[voroninp]

@captainsafia , well, I knew this, but I've learned it the hard way by making wrong assumptions. And minimal API behavior was a surprise.
This time I've noticed my colleague had wrong expectations about model validation.

[voroninp]

@captainsafia , actually, there are many places where xmldocs are lacking important details. Sometimes, clarifications can be found in docs at Microsoft.Learn. But quite often I need to look into sources.

For exception handler middleware it is not mentioned that by default 404 status code without started response will cause InvalidOperationException.

I do not get the description for this overload.
I do not specify any url, what is an alternative pipeline in this case, what for?

I'd also change the wording of the comment for adding a custom exception handler from "it is used by exception handler middleware" to "it is required to use exception handler middleware for the custom handler to work. (Analyzer would be even better;-) )

For authentication it's not obvious when Thread.CurrentPrincipal is set and when it is not.

Why is Thread.CurrentPrincipal nullable, but HttpContext.User is not?

Or another example:
While GetRouteData method uses httpContext.Request.RouteValues directly, if feature is not found, GetRouteValue method gets route values from IRouteValuesFeature.
But why?!
Why not httpContext.Request.RouteValues[key] or not:

return (httpContext.Features.Get<IRouteValuesFeature>() ?? httpContext.Request.RouteValues)[key];

Does it mean IRouteValuesFeature feature is always there? (Then it should be Features.GetRequired<IRouteValuesFeature>() to convey the intent.)
If not, then context.GetRouteData().Values[key] and `context.GetRoutValue(key)' can return differen values.
Is it a bug, or is it by design, then what was the intention?