Aspnetcore.docs: Add documentation for MVC's [Consumes] attribute

[rynowak]

See https://github.com/aspnet/Mvc/issues/7755

We're missing coverage of [Consumes] which is an attribute developers can use to limit an action to handling a set of specified content types, or choose a different action based on the request content type.

[Rick-Anderson]

@rachelappel why did you add the Source - Docs.ms label?

[Rick-Anderson]

@rynowak can you point me to some sample code and I'll get this documented this week.

[rachelappel]

@Rick-Anderson Went through a bunch of feedback items from customers and was on autopilot with the labels. Removed.

[rynowak]

This actually a very good description https://docs.oracle.com/cd/E19798-01/821-1841/gipzh/index.html - yes, I am aware that I just linked to Java's docs. This feature is designed to function basically the same way as the as the JAX-RS features

[daveabrock]

If there's no takers, I can give this a shot. One question, though: where in the docs should this reside? @Rick-Anderson @scottaddie

[Rick-Anderson]

@daveabrock start on the doc and we'll decide that later. Have a RP and MVC sample. @scottaddie - I think we need a new doc for this.

[daveabrock]

FYI, here's a link to the source code.

I've talked with @scottaddie a little about this outside of this issue, and we both think this should be in the API section. I am thinking Web API > Advanced > Control content type negotiation.

I'll put it there but feel free to move around/offer suggestions in the PR. I hope to send it over in the next day or two.

cc @Rick-Anderson @scottaddie

[Rick-Anderson]

@tdykstra please advice on the TOC
@daveabrock are you ready to do a PR?

[tdykstra]

@Rick-Anderson The suggestion Web API > Advanced > Control content type negotiation sounds OK, though it's fairly long and will wrap. When the doc contents are finalized we can see if it's possible to shorten the TOC node.

[daveabrock]

Thanks. @Rick-Anderson I'm a little swamped with a talk I have to give next week. After that, I should be able to devote some time to this one.

[Rick-Anderson]

>dotnet --version
2.2.104

The following code works with PostMan

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // POST api/values
    [HttpPost]
    [Consumes("application/json")]
    public ActionResult<string> Post([FromBody] JObject value)
    {
        return "[Consumes(&#x22;application/json&#x22;)]";
    }

    // POST api/values
    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    public ActionResult<string> Post(
        //[FromBody] string value
        )
    {
        return "[Consumes(&#x22;application/x-www-form-urlencoded&#x22;)]";
    }

When I uncomment [FromBody] string value in the x-www-form-urlencoded method, Postman returns 415 Unsupported Media Type. That's very similar to the bug reported in https://github.com/aspnet/AspNetCore/issues/4396 - but https://github.com/aspnet/AspNetCore/issues/4396 states the work around is The 2.2 workaround is to remove the ConsumesAttribute from the controller and place it on non-GET actions. which I've done.

I think the https://github.com/aspnet/AspNetCore/issues/4887 suggestion has multiple problems. For example, C# doesn't allow two identical methods. In the above I've overloaded by arg type.

I don't understand [HttpPost("api/test/bytype")]
What's the purpose of bytype

@JechoJekov | @krispenner | @AndreaCuneo | @plutext can you help me so I can get [Consumes] documented?

[Rick-Anderson]

@serpent5 do you know how [Consumes("application/json")] works?

[tdykstra]

We have some info on Consumes in the Model binding doc.

[serpent5]

@Rick-Anderson

When I uncomment [FromBody] string value in the x-www-form-urlencoded method, Postman returns 415 Unsupported Media Type.

I believe that this is because [FromBody] and x-www-form-urlencoded aren't compatible. [FromBody] signals that an InputFormatter should be used and there is no InputFormatter for x-www-form-urlencoded.

I think the aspnet/AspNetCore#4887 suggestion has multiple problems. For example, C# doesn't allow two identical methods. In the above I've overloaded by arg type.

I can't speak for @rynowak here, but I think this was just a bad copy/paste and should've been ActionForJson and e.g. ActionForUrlEncodedForm.

I don't understand [HttpPost("api/test/bytype")]
What's the purpose of bytype

I don't think bytype does have any significance here. I expect it was just to show that the route itself was being used to demonstrate different types.

---

Here's an example controller I've built and used for testing that works using the 2.2.105 SDK:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    [HttpPost]
    [Consumes("application/x-www-form-urlencoded")]
    // Use [FromForm], otherwise [ApiController] infers [FromBody].
    public IActionResult PostForm([FromForm] IEnumerable<int> values) =>
        Ok(new { ContentType = "application/x-www-form-urlencoded", Values = values });

    [HttpPost]
    [Consumes("application/json")]
    // [ApiController] infers [FromBody].
    public IActionResult PostJson(IEnumerable<int> values) =>
        Ok(new { ContentType = "application/json", Values = values });
}

If you use VS Code and its Rest Client extension, the following HTTP file might be useful for demonstrating how both of the above endpoints are being tested:

POST https://localhost:5001/api/Values
Content-Type: application/x-www-form-urlencoded

values=11&values=12&values=13&values=14&values=15

###

POST https://localhost:5001/api/Values
Content-Type: application/json

[ 11, 12, 13, 14, 15 ]

Let me know what else I can do to help with this.

[Rick-Anderson]

@scottaddie should we add ## Use [Consumes] attribute
[Consumes] is an attribute developers can use to limit an action to handling a set of specified content types, or choose a different action based on the request content type.

to Create web APIs with ASP.NET Core ?

@serpent5 if you could PR that topic with your sample that would be great.

@scottaddie should we use VS REST Client or postman to test?

[serpent5]

if you could PR that topic with your sample that would be great.

Sure. I've got a couple of things to sort out before I can get to this, but I can do it.

[Rick-Anderson]

@serpent5 thanks, no hurry.

[scottaddie]

@Rick-Anderson I'd recommend using HTTP REPL to test. It's our own product, no screenshots are needed, and the experience is consistent across all platforms. It's also supported in .NET Core 2.1 and later.

As for the proposed section, let's avoid using the attribute name in the heading. How about something like "Define the supported request content type"?

[Rick-Anderson]

@serpent5 we'd really appreciate a PR from you on this.

[serpent5]

Where should this coverage go?

1. In its own section in Create web APIs with ASP.NET Core, underneath "Problem details for error status codes".
2. In its own section in Create web APIs with ASP.NET Core, underneath "Attributes" and above "ApiController attribute".
3. In a new topic, below the existing "Web API apps > Format response data" topic. The suggested name was "Control content type negotiation", which is shorter than e.g. Manage Protobuf references with dotnet-grpc.

Other suggestions are, of course, welcome. I don't have a strong preference here, but I think it might be a little awkward trying to get it into Create web APIs with ASP.NET Core. The majority of that topic calls out the features of [ApiController], all as h1s. I also wonder if it's a bit too advanced for an overview topic.

I don't know if this warrants its own topic, though... :thinking:. Please advise.

[Rick-Anderson]

@JamesNK @scottaddie please advise where documentation for MVC's [Consumes] attribute should go.

[JamesNK]

1 is good.

It is related to attributes (2) but it is advanced, so it should at the end of the overview page.