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 https://api4u.azurewebsites.net/api/people. 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:

<toon></toon>

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 = "https://api4u.azurewebsites.net/";

7) Annotate the ToonTag class with the following:

[HtmlTargetElement("toon")]
[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.Clear();
    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) {
        System.Diagnostics.Debug.WriteLine(e.ToString());
    }
    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>";
output.Content.SetHtmlContent(html);

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.