Routing

This is the default routing set bij ASP.NET, but we are always free to change it when needed. For now let’s keep it at default . Let’s take https://localhost:5001/Employees/Detail/5 as an example. When routing this URL into our ASP.NET MVC application, it will break it apart and try to map it onto a controller route. The route called “default” is the one it will usually try, unless we specify a specific one. The pattern in the route breaks into three parts, controller/action/optional id. If we look at the URL, passed the base address, we also notice three parts, Employees/Detail/5. The route will map Employees as a controller, meaning it will search for an EmployeesController class. It will do this because, by convention, a controller ends in “Controller.” The second part is the action, in our case Detail. The system will look for a public function called Detail that returns an IActionResult and lives in the EmployeesController. Finally, because we pass in an id, the Detail method also needs to accept a parameter. Figure 7-6 shows the code for our Detail method and that the parameter of the method gets filled in through the routing system. We are getting an integer into our parameter; note that this is not a nullable int even though it looks like one in the routing template. Marking it with a question mark in the routing template just means that it is optional; the methods receiving the parameter do not need to match the optional or nullable notation; as long as the datatype matches, we should be fine.

From here, the matching view is found and inflated and passed back to the user in the form of HTML.

Views

The views in an MVC scenario are the actual pages that a user gets to see on his monitor. In ASP.NET, views are built using an HTML-like syntax called Razor. Figure 7-7 shows the views in a default ASP.NET MVC template.

Another one of ASP.NET MVC’s conventions dictates that for every controller, there is a folder containing its views. By default, we get a HomeController, so we also get a Home folder containing the views. Views are files with the *.cshtml, or *.vbhtml extensions, depending on the language we are using to write the application in. The Shared folder contains components that are reused across multiple views. Those shared components are usually prefixed with an underscore.

The rest of Index.cshtml is basic HTML code; we’ll go through some more exciting views in a minute.

Controllers

Controllers are the glue in an MVC application; they are the connector between the data and the view. As we have seen, the routing system brings us from a url straight into a controller method. In general, that method will load data from somewhere, optionally using any parameters passed into the method; it will inflate a view, execute all .NET code in that Razor view so that we end up with static generated HTML code, and send that back to the user. ASP.NET is a client-server framework; all .NET-based logic is executed on a server, and only the result, in the shape of HTML, is sent back to the client. This is simply because browsers do not understand .NET by default. Silverlight fixed this by installing an add-in in browsers so they could run compiled .NET code, but the add-in system is not ideal in today’s world of mobile browsers and devices. The next best thing is running the code on the server and sending only the result back. In short, it is very important to realize that everything in ASP.NET MVC runs on the server; only the result of a request, which is generated HTML code based on Razor files, is sent back to the client.

Let’s go through the flow of creating a new controller, method, and view to clear up how MVC and its built-in tooling work. We’ll build a controller for the Apress book collection.

We’re keeping things pretty basic for sake of the example. I’ve created a dummy BookCatalogService that returns a hardcoded list of books. We won’t go into the code for that specific service, but if you are interested you can find it on the book’s GitHub repository. For now it is just important to know that the service is registered in ASP.NET’s DI container by calling builder.Services.AddSingleton<IBookCatalogService, BookCatalogService>() in Program.cs. Now that we have our data source and DI setup, it’s time to add the controller. A controller is a class that inherits from Controller. Keep in mind that we are registering the service as singleton so that we can abuse it as an in-memory datastore.

Listing 7-11 shows the implementation of the BookController. The constructor takes the dummy BookCatalogService as a parameter. The parameter will be filled in by ASP.NET’s ServiceCollection. The Index method fetches an array of books from the service and passes that array into a method called View.

The View method that is called in the Index method comes from the Controller base class. It is used to select the correct view, depending on the name of the controller and the action method, and inflate it.

Now that we have a controller, it is time to add a view. Visual Studio provides tooling to easily add views. Adding a view can be done through right-clicking the call to View and selecting Add View.

Second step is selecting what type of view we want to generate, an empty Razor View or a scaffolded one. Scaffolding in ASP.NET is done by the Microsoft.VisualStudio.Web.CodeGeneration.Design NuGet package. The first time you launch a scaffolding command in Visual Studio this package will get added to the project. With scaffolding, we can easily generate entire parts of the application, from controller to view, including all the actions and even database operations. We will select the Razor View template . A dialog pops up where we can specify what model class we want to generate a view for, what it should be called, and what template to use. The name for the view is prefilled with the same name of the method we were just working on; the template is basically a list of basic create–read–update–delete or CRUD screens that we can take as a base for our view. Figure 7-10 shows the settings that we used for this example.

Listing 7-13 shows the top of the generated page. A Razor view can specify a model class, in this case an IEnumerable of Book. I would advise to switch from IEnumerable to a more specific interface as soon as possible, since having it as an IEnumerable has no added value whatsoever. In this case we can go with an ICollection<Book> if we wanted to. With this model attribute set, we get access to a property called Model, which is of the type we just specified using the model attribute. The anchor tag contains an asp-action attribute. It is not the default HTML anchor tag; in this case, it is an ASP.NET tag helper, an extension of existing HTML tags. The asp-action attribute takes the name of a controller action and transforms that into a correct url using the routing system in ASP.NET MVC.

For the book information, we use the Html.DisplayFor tag helper. This helper generates HTML content based on the model property we specify using a lambda. The generated HTML from DisplayFor is based on a default template that could be overwritten if needed, but that goes beyond the scope of this book. The Razor template also specifies action links to edit or delete the book or to load the details of a specific book. Those links are generated using Html.ActionLink, which is quite similar to the ASP.NET anchor TagHelper we just saw. An action link takes in a label that it will show on the actual page, a controller action, and an optional controller name for when the action we want to execute is in another controller than the one this view is linked to and some optional parameters like, for example, the id of the entity we want to delete. In the generated view code, the id is not set in the route values as the system can’t decide for us what the unique identifier is. There is commented code in the Details and Delete links that we can use to set our id.

Let’s have a look at the result of the generated page.

The generated Razor view uses the default CSS from the ASP.NET MVC template and looks rather nice. We get a good looking table, nicely listing our books and showing the generated actions. Do note that the scaffolding does not include any logic to hide primary keys or IDs from the user. So always adjust the scaffolded code to hide that information. In our case the first column in the table is the book IDs, that is, internal information that should not be leaked on screen.

Listing data on screen is quite easy; we only need to pull data from the datastore, shape it according to what we need on screen, and display it. There is a bit more work involved if we want to edit or create data. For example, let’s create the logic to add extra books to the list.

Both methods have the same name, but they have different purposes. The Create method without parameters is the one that will be called to open the form in the application. It is decorated with an HttpGet attribute , telling the MVC pipeline that this method can only be reached with a GET request. GET is the default for controller actions in MVC; however, I like to explicitly decorate the method in this case to avoid confusion. The second Create method is decorated with the HttpPost attribute so that it will only be reached via a POST method that will receive the data entered on the form. Since our form is in the shape of a book, data-wise, the ASP.NET MVC pipeline can safely bind the received value to a Book instance. If we inspect the request, we can see that the only thing that is going over the wire is basic HTML form data.

As you can see, the data going over the wire is in the shape of a book, but there is no notice of it being a book. The _RequestVerificationToken is an extra security token added by ASP.NET to verify that the received data on the server was not manipulated by a man-in-the-middle attack.

If we inspect the POST Create method , we can see that the parameter is filled in with an instance of Book, containing all the values we just entered on the form.

In a real application, we of course need to do data validation before storing the data in the datastore. For the sake of the demo, we can assume that this validation happens in the service. Once the book is added in the datastore, we redirect from the Create action to the Index action so that we end up on the list of books, including our freshly created book.

A form is a basic HTML form containing an action where the data in the form can be posted to. We are once again using ASP.NET taghelpers to generate the correct url based on controller and action names. For every property we want our users to fill in, three elements are generated, one that serves as the label. By default, the property name is shown as label but this can be overwritten. The second element is the actual input field; ASP.NET’s source generation will try to pick the correct input field based on the datatype. For a string we’ll get a text field, Boolean will give us a checkbox and so on. The third element is a placeholder for when client-side validation fails. Figure 7-14 shows the form with failed validations.

Using data annotations, we can specify required fields, minimum and maximum length, and much more.

The rest of the operations that can be generated by ASP.NET work in a very similar way so we won’t go into any more detail here. Instead, let’s have a look at another member of the ASP.NET family.

Controller-Based APIs

The type of project that you end up with depends on a specific checkbox during project creation. The project type we need is ASP.NET Core Web API. Once selected, we get a popup similar to the one we got when creating an ASP.NET MVC application.

Our REST controller inherits from ControllerBase; an MVC controller inherits from Controller, which in turn inherits from ControllerBase. So both flavors of ASP.NET are using the same base classes. The difference is that the Controller class from MVC inflates the HTML templates, something we do not need in WebAPI, so there is no need for an extra layer in between.

Listing 7-19 shows a snippet from Program.cs. The differences with MVC are AddEndpointsApiExplorer, AddSwaggerGen, UseSwagger, and UseSwaggerUI. All of these are used to configure Swagger in the project. Swagger is a third-party tool that works according to the OpenAPI Specification, or OAS. Let’s take a step back for a moment to clarify some things.

The OpenAPI Initiative (OAI) is an initiative run by a consortium of industry expert. Their aim is to describe a standardized way of how APIs should be structured. The OAI is part of the Linux Foundation, meaning it is run out in the open and completely vendor neutral. Their website is found at https://www.openapis.org/; the OAS itself is at https://spec.openapis.org/oas/latest.html

The OAS describes what the response of an API should look like, what datatypes can be used, how error messages should be structured, and so on.

Since we have an official, albeit optional, specification for our APIs, we can start building and using tools that leverage the structure the OAS described. Swagger is one of those tools; in fact, it was the people behind Swagger who drafted the first version of a Swagger Specification and donated that specification to the OAI who continued to build their version with the Swagger Specification as a solid basis. Later versions of Swagger stepped away from their Swagger Specification and started leveraging the OAS.

Listing 7-21 shows our BookController. Notice the specified route on the controller. That route is the path described in the JSON. The GET request maps to the Index method in this controller by convention; if we have multiple methods decorated with the HttpGet attribute, the system will map to the correct one based on the parameters. The Index method fetches an array of books and calls the Ok method, passing in the array of books. The Ok method is one of many helper methods in WebAPI. It creates a response object containing the data and sets the HTTP response to HTTP 200 – OK. By using those methods, we can make sure that we are respecting the OAS.

The most famous status code is no doubt HTTP 404 – Not Found. The 500 range usually means that there was an unexpected error on the backend that should be handled by the developers.

This JSON can be imported in different tools to, for example, generate client implementations that consume this API. There are even tools that do this as part of the build pipeline process. A tool included in .NET 6 is Swagger UI. Swagger UI takes the JSON and generates a visual test client for testing the API endpoints. Enabling Swagger UI in ASP.NET Core 6 is done in Program.cs by calling app.UseSwaggerUI() after app.UseSwagger().

Using Swagger UI can really speed up the dev cycle; it gives a nice overview of all endpoints, allows entering parameters, and shows the status code and errors.

We once again have a GET method; there is a route attribute on the Details method. This route will combine with the route set on the controller to get, for example, https://<hostname>:<port>/api/book/5. The 5 will be inserted as value into the id parameter of the method; it is very important to have same name for the parameter and the placeholder in the route. The method can produce two expected response types, an HTTP 200 – OK or an HTTP 404 – NOT FOUND. According to the logic in the BookCatalogService, when passing in the id, we get either a book instance or NULL back. We create the correct HTTP response using the NotFound or Ok helper methods. Swagger UI picks these changes up quite nicely, based on the two ProducesResponseType attributes we have added.

A couple of new things here. Instead of a GET request, we are now doing a POST, which is the typical verb to create a new record. The HTTP status code to return is HTTP 201 – Created, which is generated by calling the Created method. The Created method needs an endpoint where the details of the newly created book can be requested and it sends the created book back as the response body, according to the OpenAPI Specification. The parameter of the method is decorated with the FromBody attribute. The attribute ApiController on controller level enables these attributes. The FromBody attribute parses the form data in the request body to the type of the parameter. Figure 7-19 shows the resulting entry in Swagger UI.

If we fill in some values in Swagger UI, set a breakpoint in the Create action on the controller; hit the Execute button and you will see that the breakpoint is hit and the parameter is nicely filled in with the values we entered in Swagger.

Minimal APIs

As mentioned in the introduction of this chapter, minimal APIs are Microsoft’s answer to fast REST API development as can be found in frameworks like NodeJS, where you can put the entire API surface in one file. Looking at minimal APIs, we effectively have one file containing everything. From application setup to the actual endpoints, and even better: Swagger and Swagger UI know how to interpret this new style of .NET REST APIs.

Almost identical to controller-based APIs, except for the builder.Services.AddControllers call, we have no controllers in a minimal API, so no need to add them to the ServiceCollection.

The next part of Program.cs is the endpoints; after defining the endpoints, there is a small line of code that says app.Run(). These few characters make the API launch and be useful. Do not remove this call or nothing will work.

Creating a POST endpoint is very similar; we just use the MapPost method instead of MapGet. Using the FromBody attribute, we can get the posted HTTP form data as a .NET object passed into the delegate. The return type is HTTP 201 – Created.

I have only added one endpoint in Listing 7-31 for brevity. The full method with the three endpoints can be found on the book’s GitHub page. With this extension method in place, we can shorten Program.cs by calling app.MapBookEndpoints instead of defining all endpoints there.