Friday, March 6, 2020

Build an ASP.NET Core 3.1 tag helper that consumes an API RESTful service

Tag Helpers in ASP.NET Core allow you to create your own tags that fulfill a server-side purpose. In this tutorial, I will show you how to create a tag helper <toon> that accesses a Web API service and displays contents in any razor view page.

The Web API service we will consume in this exercise is located at It delivers the names of cartoon characters and their respective images.

1) To start with, create an ASP.NET Core Web application named TagHelperDemo in a terminal window using this command:

dotnet new mvc -o TagHelperDemo

2) Next, let's create a class that closely matches the nature of the Web API JSON object. Therefore, add the following CartoonCharacter class to a Models folder in your project:
public class Toon {
  public int Id { get; set; }
  public string LastName { get; set; }  
  public string FirstName { get; set; }
  public string Occupation { get; set; }
  public string Gender { get; set; }
  public string PictureUrl { get; set; }
  public int Votes { get; set; }
 3) We will need to install the API Client libraries. To that end, execute the following commands from a terminal window
dotnet add package Microsoft.AspNet.WebApi.Client
dotnet add package System.Runtime.Serialization.Xml
This should add the following dependencies to your project.json file:
<PackageReference Include="System.Runtime.Serialization.Xml" Version="4.3.0" />
<PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
 4) Add the following tag to the bottom of Views/Home/Home.cshtml:


5) Create a folder named TagHelpers and add to it a class file named ToonTag.cs. Have the class inherit from TagHelper and implement the ProcessAsync() method as follows:

public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)

We could have implemented a method Process() instead. However, in our case, it is appropriate to implement ProcessAsync() instead because we are about to make an async call to a remote service.

6) Add the following instance variable to the ToonTag class:

 private string baseUrl = "";

7) Annotate the ToonTag class with the following:

[HtmlTargetElement(Attributes = "toonie")]

The first annotation defines the tag <toon> and the second defines the “toonie” attribute. This means that we have two different ways to produce the same output on a razor .cshtml view.

8) Add the following method to the ToonTag class:

async Task<List<Toon>> GetToonsAsync() {
    HttpClient client = new HttpClient();
    client.BaseAddress = new Uri(baseUrl);
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    List<Toon> toons = null;
    try {
        // Get all cartoon characters
        HttpResponseMessage response = await client.GetAsync("/api/people");
        if (response.IsSuccessStatusCode) {
            string json = await response.Content.ReadAsStringAsync();
            toons = JsonConvert.DeserializeObject<List<Toon>>(json);
    } catch (Exception e) {
    return toons;

The above code makes a request to the Web API service and returns an List<Toon> collection with the results.

9) Add the following code inside the ProcessAsync() method:

List<Toon> toons = await GetToonsAsync();
string html = string.Empty;
html += "<table><tr><th>Name</th><th>Picture</th></tr>";
foreach (var item in toons) {
    html += "<tr>";
    html += "<td>" + item.FirstName + " " + item.LastName + "</td>";
    html += "<td><img src='" + item.PictureUrl + "' style='width: 50px' /></td>";
    html += "</tr>";
html += "</table>";

The above code creates a table with the collection of toon characters so that it can be displayed wherever the tag helper is used.

11) Register the tag name in the Views/_ViewImports.cshtml file by adding the following to the list of tags that are already there:

@addTagHelper "TagHelperDemo.TagHelpers.ToonTag, TagHelperDemo"

You may need to adjust the above names depending on what you called your app and/or your tag helper class.

11) Compile and run your application. You should see the following output:

If you inspect the table in your browser, you will see the following:

The above is using the tag and not the attribute.

Edit Home.cshtml and comment out “<toon></toon>” and put the following <div> tag with the toonie attribute underneath it:
<div toonie></div>

When you run your application. you should see the same output as before. If you inspect the table you will see the following HTML source:

This proves to us that you can either use tags or attributes with TagHelpers in ASP.NET Core.

No comments:

Post a Comment