Add Web API controller definition doc #6003

scottaddie · 2018-04-17T18:34:57Z

Addresses #5401

This is a new doc explaining the various ways to create a Web API controller. The ASP.NET Core 2.1 [ApiController] attribute is covered in it.

Internal Review Page

rynowak · 2018-04-19T19:41:39Z

aspnetcore/web-api/define-controller.md

@@ -0,0 +1,113 @@
+---
+title: Define a controller in ASP.NET Core Web API


I have a bone to pick with this branding @DamianEdwards @danroth27 are we still using the Web API branding? If I'm wrong about this I'll just go away 😆

We shouldn't use "ASP.NET Core Web API". Suggested title: "Building web APIs with ASP.NET Core"

rynowak · 2018-04-19T19:44:09Z

aspnetcore/web-api/define-controller.md

+
+This document explains when it's most appropriate to use each option.
+
+## Derive class from Controller


The document seems focused on APIs, I think it's good to do a comparison, but explain that Controller is recommended for HTML and Razor.

To most users this won't make a big difference, but it's possible in the future we'd ship a remixed framework that doesn't include Controller by default.

rynowak · 2018-04-19T19:46:42Z

aspnetcore/web-api/define-controller.md

+
+[!code-csharp[](../web-api/define-controller/samples/WebApiSample.Api/Controllers/ProductsController.cs?name=snippet_ControllerSignature&highlight=2)]
+
+This attribute is commonly coupled with either `ControllerBase` or `Controller` to gain access to useful methods and properties. `ControllerBase` provides access to methods such as [CreatedAtAction](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.createdataction) and [File](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.file). `Controller` provides access to methods such as [Json](/dotnet/api/microsoft.aspnetcore.mvc.controller.json) and [View](/dotnet/api/microsoft.aspnetcore.mvc.controller.view).


You can also create your own base class and slap [ApiController] on it. There's nothing magic about Controller or ControllerBase.

You can also create your own base class and slap [ApiController] on it. There's nothing magic about Controller or ControllerBase.

Can you suggest why you'd want to do that?

Sure, lots of folks like to do one of two things:

Give us lots of specific feedback about specific action-result-creating methods they want to see or change

Create an ApiController base class because they like that idea

Users can solve both of these problems for themselves. They can create their own base class that either inherits from ControllerBase, slap [ApiController] on it and they are good to go.

rynowak · 2018-04-19T19:58:40Z

aspnetcore/web-api/define-controller.md

+
+### Binding source parameter inference
+
+Inference rules are applied for the default data sources of action parameters. The binding source attributes behave as follows:


I think before digging into the details it would be good to show an example and explain the common patterns. Most APIs will bind a parameter (or two from the route) - usually an int or string, and a parameter or two from the query string - usually a simple type, and usually a complex type from the body.

It would be good to show how the [ApiController] attribute cleans up the code by inferring the details of the idiomatic approach for binding in APIs

rynowak · 2018-04-19T19:59:39Z

aspnetcore/web-api/define-controller.md

+
+[!code-csharp[](../web-api/define-controller/samples/WebApiSample.Api/Controllers/TestController.cs?name=snippet_ActionsCausingExceptions)]
+
+* **[[FromForm]](/dotnet/api/microsoft.aspnetcore.mvc.fromformattribute)** is inferred for action parameters of type [IFormFile](/dotnet/api/microsoft.aspnetcore.http.iformfile) and [IFormFileCollection](/dotnet/api/microsoft.aspnetcore.http.iformfilecollection).


It would be good to add that [FromForm] won't be inferred for any simple or user-defined types. If you want to bind form data in an api controller, you should tell us about it because it's not super common

rynowak · 2018-04-19T20:00:48Z

...ore/web-api/define-controller/samples/WebApiSample.Api.Pre21/Controllers/OrdersController.cs

+        [HttpGet("{id}")]
+        [ProducesResponseType(typeof(Order), 200)]
+        [ProducesResponseType(404)]
+        public IActionResult GetById(int id)


This should use ActionResult<Order>

That allows you to remove the [ProducesResponseType] attribute when it's a 200.

This is a 2.0 version of the sample app, which is why it doesn't use ActionResult.

scottaddie · 2018-04-23T19:43:00Z

@rynowak Please take another look.

rynowak · 2018-04-23T20:11:01Z

aspnetcore/web-api/index.md

+
+## Derive class from Controller
+
+Inherit from the [Controller](/dotnet/api/microsoft.aspnetcore.mvc.controller) class in a controller that needs to support HTML and Razor in addition to web API actions. Examples that require `Controller` inheritance include returning MVC views or [invoking view components](xref:mvc/views/view-components#invoking-a-view-component-directly-from-a-controller).


in a controller that needs to support HTML and Razor in addition to web API actions.

I don't really know what that's a topic. You certainly could write a controller that serves both APIs and views, but I don't think we'd recommend that users do this on purpose.

Should I add a note explaining this approach isn't recommended? It's here since the project template used to derive from Controller.

Regardless of what it used to derive from, I don't understand why we would discuss it as a controller that needs to support HTML and Razor in addition to web API actions - this isn't something we've ever really told people to do. It's not explicitly recommended or disrecommended, which is why I'm suprised to see it getting coverage here.

@danroth27 Thoughts?

👍 to @rynowak's comment. I don't think we need to discuss deriving from Controller in this topic or anything views related.

rynowak · 2018-04-23T20:11:27Z

aspnetcore/web-api/index.md

+[!code-csharp[](../web-api/define-controller/samples/WebApiSample.Api/Controllers/ProductsController.cs?name=snippet_ControllerSignature&highlight=2)]
+
+This attribute is commonly coupled with either `ControllerBase` or `Controller` to gain access to useful methods and properties. `ControllerBase` provides access to methods such as [CreatedAtAction](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.createdataction) and [File](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.file). `Controller` provides access to methods such as [Json](/dotnet/api/microsoft.aspnetcore.mvc.controller.json) and [View](/dotnet/api/microsoft.aspnetcore.mvc.controller.view). Another approach is to create a custom base controller class annotated with the `[ApiController]` attribute.
+


Add Web API controller definition doc

39c56df

scottaddie added the WIP label Apr 17, 2018

scottaddie added 16 commits April 17, 2018 13:40

Remove wwwroot folder reference from csproj file

f6cb514

Verbiage tweaks

28ba86e

Add info about FromForm inference

e5ab1c9

Bold the attribute names

2183485

Add TOC entries

c7f4d30

Change link ordering in TOC

403f2f1

Add note about IntelliSense

18faa47

Major sample app changes

484b1ab

Fix code snippet line numbers

2a5bd8a

Minor verbiage tweaks

10c9c3f

Add a README file

e9a1da9

Add TestController.cs

d279a55

Verbiage changes

4bffbfd

Shorten wording

5763966

Change wording

6dd85f1

Minor edit

0e2bba9

scottaddie changed the title ~~[WIP] Add Web API controller definition doc~~ Add Web API controller definition doc Apr 19, 2018

scottaddie removed the WIP label Apr 19, 2018

scottaddie requested review from rynowak and Rick-Anderson April 19, 2018 16:32

rynowak reviewed Apr 19, 2018

View reviewed changes

Rick-Anderson approved these changes Apr 20, 2018

View reviewed changes

React to feedback

ecdf8ca

scottaddie added 9 commits April 23, 2018 12:41

Add attributes table

3932ec7

Verbiage tweaks

11ae6cb

querystring -> query string

7e883bc

Minor edit

916c999

Add 2.1 controller samples

f010d89

Fix invalid moniker names

da136e5

Update code sample to 2.1

f58d262

Update line number

b2371af

Convert uppercase W to lowercase

5401a72

rynowak reviewed Apr 23, 2018

View reviewed changes

rynowak approved these changes Apr 23, 2018

View reviewed changes

scottaddie added 6 commits April 24, 2018 13:36

React to feedback

c2658cc

Update sample app's README file

e790d33

Project file cleanup

5d45cb5

Replace word

6b2192e

Remove MVC views from sample app

7a43402

Derive from ControllerBase instead of Controller

c1b589d

scottaddie merged commit d771655 into master Apr 24, 2018

scottaddie deleted the scottaddie/define-controller-doc branch April 24, 2018 19:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Web API controller definition doc #6003

Add Web API controller definition doc #6003

scottaddie commented Apr 17, 2018 •

edited

Loading

rynowak Apr 19, 2018

danroth27 Apr 19, 2018

rynowak Apr 19, 2018

rynowak Apr 19, 2018

Rick-Anderson Apr 19, 2018

rynowak Apr 19, 2018

rynowak Apr 19, 2018

rynowak Apr 19, 2018 •

edited

Loading

rynowak Apr 19, 2018

rynowak Apr 19, 2018

scottaddie Apr 23, 2018

scottaddie commented Apr 23, 2018

rynowak Apr 23, 2018

scottaddie Apr 23, 2018

rynowak Apr 23, 2018 •

edited

Loading

scottaddie Apr 23, 2018

danroth27 Apr 24, 2018

rynowak Apr 23, 2018

		@@ -0,0 +1,113 @@
		---
		title: Define a controller in ASP.NET Core Web API


		This document explains when it's most appropriate to use each option.

		## Derive class from Controller


		[!code-csharp[](../web-api/define-controller/samples/WebApiSample.Api/Controllers/ProductsController.cs?name=snippet_ControllerSignature&highlight=2)]

		This attribute is commonly coupled with either `ControllerBase` or `Controller` to gain access to useful methods and properties. `ControllerBase` provides access to methods such as [CreatedAtAction](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.createdataction) and [File](/dotnet/api/microsoft.aspnetcore.mvc.controllerbase.file). `Controller` provides access to methods such as [Json](/dotnet/api/microsoft.aspnetcore.mvc.controller.json) and [View](/dotnet/api/microsoft.aspnetcore.mvc.controller.view).


		### Binding source parameter inference

		Inference rules are applied for the default data sources of action parameters. The binding source attributes behave as follows:


		[!code-csharp[](../web-api/define-controller/samples/WebApiSample.Api/Controllers/TestController.cs?name=snippet_ActionsCausingExceptions)]

		* [[FromForm]](/dotnet/api/microsoft.aspnetcore.mvc.fromformattribute) is inferred for action parameters of type [IFormFile](/dotnet/api/microsoft.aspnetcore.http.iformfile) and [IFormFileCollection](/dotnet/api/microsoft.aspnetcore.http.iformfilecollection).


		## Derive class from Controller

		Inherit from the [Controller](/dotnet/api/microsoft.aspnetcore.mvc.controller) class in a controller that needs to support HTML and Razor in addition to web API actions. Examples that require `Controller` inheritance include returning MVC views or [invoking view components](xref:mvc/views/view-components#invoking-a-view-component-directly-from-a-controller).

Add Web API controller definition doc #6003

Add Web API controller definition doc #6003

Conversation

scottaddie commented Apr 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rynowak Apr 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scottaddie commented Apr 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rynowak Apr 23, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

scottaddie commented Apr 17, 2018 •

edited

Loading

rynowak Apr 19, 2018 •

edited

Loading

rynowak Apr 23, 2018 •

edited

Loading