(Apologies – this turned into quite a lengthy blog post. Hopefully it took longer to write than it’ll take to follow along – if you need to, skip to the final bits about Typed HttpClientFactories and Refit).
(Apologies 2 – turned out I pasted the wrong code in for the Typed Http Clients – now amended. Thanks for the feedback).
To keep things fairly simple, the main aim of this blog post is to retrieve some data from the Student Record System (SRS) Web API application by a call from the DataViewer Web Application and display the data received. Not much love will go into the display of the data (that may come in a later blog post), this will be focusing on the concepts of communicating.
There are a number of ways to achieve this in .NET Core – some that are suitable for production code, and some, well, less so. I’m going to try and walk through each method in turn so we can explore them all, and perhaps try and point out some of the limitations with each approach (and defer to related blog articles from authors who can write much better than myself and cover the details in a much greater depth).
First Step – Removing SSL
To avoid having to set-up SSL certificates, change the launchSettings for the SRS project to be http – to do this expand the Properties node and open the launchSettings.json file. Change the address from the previous blog post from https://localhost:5100 to http://localhost:5100.
Setting Up Some Data
In the Web API application (SRS), click on the Project and click Add->New Folder and call the folder Models.
Then right click on this new folder and add a class and name it ‘Student’.
We’ll then add some properties to this Student class, keeping them simple for now.
(Quick Tip: A short-cut in Visual Studio exists to type prop and then press Tab and Tab afterwards. This generates the scaffold code for a property.)
We’re going to add strings for First Name, Last Name, Email and Student ID.
(Quick Tip: It would also be nice to include a photo, but we’ll flag this as something to come back to. You can flag TODO items in the code by using the comment syntax with TODO – as shown in the code below. All these entries then show up in the Task List in Visual Studio.)
We also need to add 2 constructors – one empty to aid serialisation (something we’ll come back to later) and then another to all the creation of a new student with the properties being set at creation.
(Quick Tip: A short-cut in Visual Studio exists to type ctor[tab][tab] and this will generate to constructor signature for you.)
namespace StudentRecordSystem.Models
{
public class Student
{
// TODO: Add Student Photo/Image
public string FirstName { get; set; }
public string LastName { get; set; }
public string Email { get; set; }
public string StudentId { get; set; }
}
public Student()
{
}
public Student(string firstName, string lastName, string email, string studentId)
{
FirstName = firstName;
LastName = lastName;
Email = email;
StudentId = studentId;
}
}
Next we’ll introduce a controller to then serve up a list of students. On the controllers folder, right click and Add->Controller…
Select API – Empty Controller and enter StudentController as the name.
In this controller we need to first annotate the controller itself with [Produces(“application/json”)] – I think this is the default anyway if not specified, but best to be explicit.
Then implement the Get method to return some student data – see below for the example code:
[Route("api/[controller]")]
[ApiController]
[Produces("application/json")]
public class StudentController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
List students = new List();
students.Add(new Student("Anna", "Annabel", "a.a@uni.ac.uk", "1234"));
students.Add(new Student("Brian", "Beater", "b.b@uni.ac.uk", "1235"));
return Ok(students);
}
}
With this in place, start the app again (as per the previous blog post) and then view the /api/Student URL and you should get JSON output of the students specified above.
With this in place now, we can return to the Web App and make a call to this API and start to display the data.
Multiple Ways To Call Web APIs
1. The HttpClient – The simplest, but perhaps problematic
In the DataViewer Web App, right click on the Controllers folder and ‘Add’ and New Controller. This time select Empty MVC controller, and call it StudentController.
Within this controller will be default method called Index(). Within it place the following code:
public async Task Index()
{
var url = “http://localhost:5100/api/Student”;
var client = new HttpClient();
var response = await client.GetStringAsync(url);
return response;
//return View();
}
The code above essentially defines the URL to call, and then creates an HttpClient object. It then uses the helper method .GetStringAsync to call the address and read the string returned. Finally we return this string straight to the browser. In a future step we’ll look at tidying up this display.
Thats it, but this method comes with a caveat. Steve Gordon covers this in excellent detail in his little series on HttpClientFactory, so I don’t plan to recover it here ( https://www.stevejgordon.co.uk/introduction-to-httpclientfactory-aspnetcore) (and I’ve also linked to the ASP.NET Monsters post about this issues), but essentially every time this method is executed we create a new HttpClient, and secondly the lifetime of the client isn’t handled very well, which could lead to issues in a scaled environment.
1b. Formatting the data output
Before going too much further, lets take the data returned and format it. For this we’ll use a 3rd party library – Newtonsoft.Json.
a. Right click on the DataViewer application project and select Manage NuGet Packages…
b. Ensure the ‘Browse’ tab is selected. You may not need to search for anything, it was the first list library for me. (otherwise search for Newtonsoft). Click and select the ‘Install’ option. (and OK any other pop-ups).
c. Next we need to add a model to represent the data returned. This will essentially be the same as the Student class created in the SRS project. As such, on the Models folder, right click and add new class, named Student. Enter the following code:
public class Student
{
// TODO: Add Student Photo/Image
public string FirstName { get; set; }
public string LastName { get; set; }
public string Email { get; set; }
public string StudentId { get; set; }
public Student()
{
}
public Student(string firstName, string lastName, string email, string studentId)
{
FirstName = firstName;
LastName = lastName;
Email = email;
StudentId = studentId;
}
}
d. Next, update our controller to now convert the Json String to a List of Student Models. The code is as follows:
public async Task Index()
{
var url = "http://localhost:5100/api/Student";
var client = new HttpClient();
var response = await client.GetStringAsync(url);
List students = JsonConvert.DeserializeObject(response);
return View(students);
}
The code above is very similar to the code previously provided except:
i. We’ve changed the return type.
ii. We’ve introduced JsonConvert (from Newtonsoft.Json) to convert the string returned to a List of students.
iii. We return to a view (which is created next) which uses the list of students to create a table (nothing pretty yet, but we’ll tidy up to use Bootstrap in a future blog post).
e. Create a new View. First, expand the Views folder and then create a new folder of ‘Student’ (NB. it must match the Controller name provided previously). Then right click on this new folder and create a View, give it the name of Index and create it. Enter the following code to just output a table:
@model List
@{
ViewData["Title"] = "Index";
}
<h1>Index</h1>
<table>
<tr>
<th>Photo</th>
<th>First Name</th>
<th>Last Name</th>
<th>Email</th>
<th>Student ID</th>
</tr>
@{
foreach (var item in @Model)
{
<tr>
<td>TBD</td>
<td>@item.FirstName</td>
<td>@item.LastName</td>
<td>@item.Email</td>
<td>@item.StudentId</td>
</tr>
}
}
</table>
Run up both apps, and now see that you’re getting a Web Page with a table of the student data, as opposed to the raw JSON.
2. Using Named HttpClientFactories
An alternative method by using HttpClientFactories was introduced with .NET Core 2.1. In this approach you can declare a factory to be used instead of creating the client upon every request. Some of the benefits are slight efficiencies, the factory will manage the lifetimes of the HttpClients on your behalf and you’ve a central place for all requests to a location in your app, rather than potentially being scattered throughout your application (a good approach should you ever need to change the location of the other service). Its probably best explained with an example.
In Startup.cs of the DataViewerApp, add the following code to the ConfigureServices() method:
services.AddHttpClient("StudentRecordSystem", s =>
{
s.BaseAddress = new Uri("http://localhost:5100/");
// Optionally add additional header information, e.g. keys etc... not required in this example.
});
Next we need to use Dependency Injection to pass the factory to the controller, before then using it instead of the calls we were previously making.
So in the StudentController.cs, introduce a Constructor (Remember the short-hand tip from earlier). Then make the controller look as follows:
public class StudentController : Controller
{
private readonly IHttpClientFactory _clientFactory;
public StudentController(IHttpClientFactory clientFactory)
{
_clientFactory = clientFactory;
}
public async Task Index()
{
List students = new List();
var request = new HttpRequestMessage(HttpMethod.Get, "api/Student");
var client = _clientFactory.CreateClient("StudentRecordSystem");
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
students = await response.Content.ReadAsAsync();
}
return View(students);
}
}
Run up the apps and ultimately nothing has changed, but we’ve made the code a little bit better along the way.
3. Using Typed HttpClientFactories
One major drawback of the ‘Named’ approach above is that the strings need to match in both places and as such is liable to typo errors (and the compiler won’t help you with this – you’ll get run time problems). Also the calls to specific endpoints are also still scattered throughout the code.
An alternative method to overcome some of these limitations is typed clients. Again, an example may be the easiest way to explain.
In the DataViewer app, right click on the project and Add->New Folder and call it ‘Services’. Then right click on the folder and Add->Class… and call this StudentRecordSystemService. Then implement the code outlined below:
public class StudentRecordSystemService
{
public HttpClient Client { get; }
public StudentRecordSystemService(HttpClient client)
{
client.BaseAddress = new Uri("http://localhost:5100/");
// Optionally add additional header information, e.g. keys etc... not required in this example.
Client = client;
}
public async Task GetStudentsAsync()
{
var response = await Client.GetAsync("api/Student");
response.EnsureSuccessStatusCode();
return await response.Content.ReadAsAsync();
}
}
This seems a bit more involved, but ultimately derives a number of benefits in the calling code base – the changes which are outlined below. In Startup.cs, replace the code we added previously with the following:
services.AddHttpClient();
And then change the code in the StudentController to match the code below:
public class StudentController : Controller
{
private readonly StudentRecordSystemService _studentRecordService;
public StudentController(StudentRecordSystemService studentRecordService)
{
_studentRecordService = studentRecordService;
}
public async Task Index()
{
List students = await _studentRecordService.GetStudentsAsync();
return View(students);
}
}
Again, start the apps and check our student table comes back as expected. We’ve now got the benefit of all the calls being made in a single place, using a typed client factory, alongside creating a folder for a common area for all API calls to be stored and sit side-by-side. Finally, the code in the callers becomes much more simplified.
4. Using Refit
Finally, we can refine things further by using a 3rd party library called refit.
First, add a reference to the NuGet package ‘Refit’ (right click on DataViewer Project and click Manage NuGet Packages). Then browse for the ‘Refit’ library and install it.
Then add an Interface (Add->New Class) to the Services folder and implement the following code:
public interface IStudentRecordSystemService
{
[Get("/api/Student")]
Task GetStudentAsync();
}
Next change the StudentController to match the following:
public async Task Index()
{
// Missing try...catch for error handling.
var srsClient = RestService.For("http://localhost:5100/");
List students = await srsClient.GetStudentAsync();
return View(students);
}
And thats it. We can now remove code in the Startup.cs if we wish, along with the StudentRecordSystemService.cs. Again, run the app and ensure everything is running.
References:
https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests?view=aspnetcore-2.2
HttpClientFactory in ASP.NET Core 2.1 (Part 1)
https://aspnetmonsters.com/2016/08/2016-08-27-httpclientwrong/
https://www.projectcodify.com/creating-a-rest-api-wrapper-using-refit
