Understanding ASP.NET Core Solutions

ASP.NET Core solutions are based on the MSBuild solution system (.sln files) and on the C# project system (.csproj). In the Solution pad, you can see a number of files and folders. Table 10-1 summarizes the most important elements that compose an ASP.NET Core solution.

If you have built ASP.NET MVC applications in the past, you will see that there are many commonalities between ASP.NET MVC solutions and ASP.NET Core MVC solutions. There are certainly important differences, but the structure of a Core solution should at least sound familiar. In the next sections, you will start writing code that interacts with the Computer Vision service by creating an appropriate controller and a convenient user interface that will help users upload an image for analysis. You will also see how to implement data access with Entity Framework Core.

The Model: Working with Entity Framework Core

Entity Framework Core is a lightweight, cross-platform version of the popular and successful object relational mapping (ORM) engine from Microsoft. With Entity Framework Core, you can write C# classes that represent a table in the database (entities) and have properties represent columns in the table. Then, you read, write, and manage a database using a data context C# class.

This way, you work in a strongly type, .NET-oriented approach, and because Entity Framework provides an abstraction layer, it can be used in the same way against several data stores, such as SQL Server and SQLite. In the pure philosophy of .NET Core, Entity Framework Core entirely ships as NuGet packages. In this section, you will see how to include Entity Framework Core in your ASP.NET Core app to store a list of image file names and the result of Computer Vision recognition. If you need more information about Entity Framework, you can visit http://docs.microsoft.com/en-us/ef/ .

First, you need a model class that represents the information you want to store in a database. This is called a code-first approach. Put succinctly, with the code-first approach, you can start with a simple class definition, and Entity Framework will do the work for you to persist objects to a data store just by using that class.

For instance, you might want to store the image file name, the result of the image analysis returned by the Computer Vision APIs, and a timestamp. To accomplish this, by reusing the knowledge you got in the previous chapters, create a new folder called Models in the project and add a new class file called ImageData.cs. When ready, add the following code:

public class ImageData
{
    public int Id { get; set; }
    public string ImageName { get; set; }
    public string AnalysisResult { get; set; }
    public DateTime TimeStamp { get; set; }
}

Notice the Id property, which Entity Framework will use as the primary key for the corresponding table. The next step is to add some NuGet packages, but first you have to decide what kind of data store you want to use. In real-world applications, you might want to consider SQL Server or SQL Azure as the data store, but in this chapter I will be showcasing SQLite. The reason is that SQL Server is not available for macOS, and therefore you could not test this option locally; additionally, not all readers might have the opportunity to test Entity Framework against a remote SQL Server. Instead, it is interesting to demonstrate .NET Core’s capabilities to work against the serverless, portable SQLite data store that is available on all platforms. You will then be able to use almost the same techniques with a different data store, just choosing the appropriate NuGet packages. In the case of SQLite, the NuGet packages you need are as follows:

• Microsoft.EntityFrameworkCore.SQLite

• Microsoft.EntityFrameworkCore.Design

These provide all the .NET objects required to work against a SQLite database. In the case of SQL Server, you would instead download the Microsoft.EntityFramework.SQLServer and Microsoft.EntityFrameworkCode.SQLServer.Design packages. If you have worked with Entity Framework and .NET Framework in the past, you know that you need a class that inherits from DbContext in order to interact with a database, tables, and columns, and to read and write data. A DbContext class exposes properties of type DbSet<T>, where each property basically represents a table in the database in the form of a C# collection. So, in this case, you need a DbContext class that exposes a property of type DbSet<ImageData>. Having that said, in the Models folder, add a new class file called ImageContext.cs with the following code:

using System;
using Microsoft.EntityFrameworkCore;

namespace CrossComputerVision.Models
{
    public class ImageContext : DbContext
    {
        public DbSet<ImageData> ImageList { get; set; }

        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
        {
            optionsBuilder.UseSqlite("Data Source=ComputerVision.db");
        }
    }
}

Notice how the class must override the OnConfiguring method in order to supply a connection string via the DbContextOptionsBuilder.UseSqlite instance method. The connection string contains the name of the local database, which you can replace with a different name of your choice. The next step is to generate the database through Entity Framework Core, which is accomplished via code migrations. Put succinctly, code migrations allow you to update the database schema incrementally, every time you make edits to your C# data model. When you apply code migrations, Entity Framework generates some C# code files that are responsible for updating the database schema. At this writing, there is no built-in tool in Visual Studio for Mac that allows you to generate code migrations from within the IDE, so you need to use the dotnet.exe command-line tool. Additionally, command-line tools for Entity Framework are not included by default in the .NET Core SDK, so you need to manually add an additional reference into the .csproj project file. To accomplish this, in the Solution pad, right-click the project name and then select Tools ➤ Edit File. This opens the .csproj file of the sample project in the XML code editor. At this point, add the following XML node:

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet"
      Version="1.0.1" />
</ItemGroup>

This will add command-line tools for Entity Framework Core to the current project. Save the .csproj file, and you will see how Visual Studio for Mac will reload NuGet packages, but this is not enough. With the help of the Finder system application, open a Terminal instance inside the project folder. The project folder is the one that contains the .csproj file, not the solution file. When ready, type the following command:

> dotnet restore

This command will cause .NET Core to restore NuGet packages for the project and will download and include the tools you specified. The next step is to create a first code migration that you accomplish with the following command:

> dotnet ef migrations add FirstMigration

When you create a code migration, you need to supply a migration identifier, FirstMigration in this case. You can replace this identifier with another one of your choice, and you are totally free to decide the identifiers you want to use. The final step is to update the database, and because this is the first code migration, the database will also be created. This is accomplished with the following simple line:

> dotnet ef database update

You will see in the Terminal a list of SQL commands that Entity Framework Core uses to generate the SQLite database. At this point, you have completed setting up the data context and the data model. You will write code that interacts with the context and the database in a specific controller, as discussed in the next section.

Working with Controllers

Controllers are C# classes that contain the code that executes actions against a data source, such as a database or a web service, according to the required business logic. Any new ASP.NET Core project contains a controller called HomeController.cs that defines methods that invoke the proper pages in the user interface, such as Index, About, and Contact. These methods are also referred to as actions. In Visual Studio, there is a page for each action under the Views project folder. This one contains as many subfolders as many controllers you have in your project, and each subfolder contains view pages whose name recalls the name of an action.

For example, the HomeController class has the Index, About, and Contact actions. So, in the Views folder, there is a Home subfolder that contains the Index.cshtml, About.cshtml, and Contact.cshtml pages. Then the ASP.NET Core runtime knows what page it needs to launch according to the action. In the sample application, for a better separation of the logic, you will create a new controller called VisionController.cs, which you add in the Controllers folder. Right-click this folder, then select Add ➤ New File, and in the New File dialog select the MVC Controller Class item, as shown in Figure 10-5.

Figure 10-5. Creating an MVC controller

The purpose of the new controller is to expose an action called Vision that sends an image file to the Computer Vision API’s endpoint and that elaborates the response that the service sends back. In the constructor, you create an instance of the ImageContext class that will be used to persist the image analysis results.

ImageContext context;
public VisionController()
{
    context = new ImageContext();
}

Before implementing the action, a couple of preliminary considerations are necessary. In ASP.NET Core, a file is represented by an object of type IFormFile. Implementations of this type expose a method called OpenReadStream, which is used to read the content of the file under the form of a Sytem.IO.Stream object . ASP.NET Core uses streams because accessing the file system directly is something that would require platform-specific implementations, but this is not possible in the .NET Core cross-platform environment. Then the file is converted into an array of bytes through a MemoryStream object and its ToArray method. Because your goal is also to display the image in the user interface within an img HTML control later, it is necessary to convert the byte array into a string encoded with 64-base digits that such a control can read. This is accomplished with the following code:

private string FileToImgSrcString(IFormFile file)
{
    byte[] fileBytes;
    using (var stream = file.OpenReadStream())
    {

        using (var memoryStream = new MemoryStream())
        {
            stream.CopyTo(memoryStream);
            fileBytes = memoryStream.ToArray();
        }
    }

    return BytesToSrcString(fileBytes);
}

private string BytesToSrcString(byte[] bytes) => "data:image/jpg;base64," +
        Convert.ToBase64String(bytes);

The next code is about the implementation of the Vision action , which includes a constant that stores the secret key generated by the Azure Portal for the Computer Vision APIs. Type the following code, and then comments will be provided shortly:

public const string _apiKey = "YOUR-KEY-GOES-HERE";

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Vision(IFormFile file)
{
    //put the original file in the view data
    ViewData["originalImage"] = FileToImgSrcString(file);
    string result;

    using (var httpClient = new HttpClient())
    {
        // Request parameters
        var baseUri =
            "https://westeurope.api.cognitive.microsoft.com/vision/v1.0/
            analyze?visualFeatures=Description";

        //setup HttpClient
        httpClient.BaseAddress = new Uri(baseUri);
        httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", _apiKey);

        //setup data object
        HttpContent content = new StreamContent(file.OpenReadStream());
        content.Headers.ContentType =
                new MediaTypeWithQualityHeaderValue("application/octet-stream");

        //make the request
        var response = await httpClient.PostAsync(baseUri, content);

        var responseContent = response.Content as StreamContent;
        // get the string for the JSON response
        var jsonResponse = await responseContent.ReadAsStringAsync();

        // Deserialize the JSON response to retrieve the analysis result
        var jresult = JObject.Parse(jsonResponse);
        result = jresult["description"]["captions"].First.ToString();
    }

    ImageData imageInfo = new ImageData();
    imageInfo.TimeStamp = DateTime.Now;
    imageInfo.ImageName = file.FileName;
    imageInfo.AnalysisResult = result;

    context.ImageList.Add(imageInfo);
    await context.SaveChangesAsync();

    ViewData["result"] = result;
    return View(context.ImageList.ToList());
}

ViewData is a property of controllers and is of type ViewDataDictionary. You may think of ViewData as a dictionary that you can populate with key/value pairs dynamically. In practice, in the HTML markup, you will be able to invoke C# code and bind property values directly into the markup. This way, with ViewData you can send to the user interface the information you want to display. In this case, ViewData is used to send to the user interface the image and the analysis result. All of the Cognitive Services receive HTTP POST requests and return a JSON response.

To send a POST request, you use the HttpClient class and its PostAsync method . You first supply the service URL as the HttpClient.BaseAddress value and the secret key in the request headers, by invoking the HttpClient.DefaultRequestHeaders.Add method and supplying a key/value pair made of the Ocp-Apim-Subscription-Key key and your secret key as the value. The content of the POST request (HttpContent) contains the image encapsulated in a StreamContent object, populated with the IFormFile.OpenReadStream method. PostAsync receives a response from the Computer Vision service in the form of a StreamContent object that is converted into a string returned by ReadAsStringAsync. This conversion is required because the response actually contains JSON , which is an indented string. The following JSON exemplifies the structure of a response you receive by the service:

{  
     "description":
     {     
         "tags":
         [       
             "person",       
             "man",       
             "outdoor",       
             "building",       
             "smiling",       
             "camera",       
             "standing",       
             "holding",       
             "sitting",       
         ],
         "captions":
         [
             {
                 "text": "a man smiling for the camera",
                 "confidence": 0.95715732768096673
             }
         ]   
     },   
     "requestId": "ddfccd26-96d3-45bf-95c2-c36559d67186",   
     "metadata":
     {     
         "width": 234,     
         "height": 234,     
         "format": "Jpeg"   
     }
}

As you can see, an array of tags contains autogenerated categorization tags for the image, but this is not required for the sample application. The goal is retrieving the text and confidence contained in the captions array, so the code must deserialize this JSON string into an object that can be further elaborated.

ASP.NET Core projects already include the popular Newtonsoft.Json library that can be quickly used to parse JSON content into .NET types. The Newtonsoft.Json.Linq.JObject.Parse method is used to get an array of values, and the result of the image analysis is actually the first value in the array called captions, nested in the description JSON element. The resulting string contains the type and result of the image analysis. Once you have the image analysis result, you can create an instance of the ImageData class and store the result itself, the timestamp, and the file name. Then the new instance is added to the collection of ImageData called ImageList, and the data is saved using the SaveChangesAsync method of the DbContext class. This means you are adding a new row to the table in the database, using a completely .NET-oriented approach. Notice the return statement: the View method will search for a view that is bound to the Vision action , passing the ImageList collection as the data for the view. This is demonstrated in the next section about views. The last piece of code the controller needs is an action called Index, which returns the default view for the controller and which looks like the following method:

public IActionResult Index()
{
    return View();
}

Now that you have a controller ready, it is time to implement a basic user interface and see how the controller works against the Computer Vision API service.

Working with Views

In the MVC pattern, views represent the user interface. In the case of a web application, views are pages that a web browser can render. In ASP.NET Core, pages are (usually) .cshtml files. This kind of file can be considered an evolution of HTML files, in that they fully support the well-known markup language, plus they extend the opportunities by using additional controls and by embedding C# code directly into the HTML code. Visual Studio for Mac provides a great experience when editing HTML files with the usual power. In fact, it provides not only syntax colorization but also word completion based on the context, as you can see in Figure 10-6 and as you will discover while typing the markup code described in this section.

Figure 10-6. The HTML editor provides syntax colorization and word completion as you type

When you create a new ASP.NET Core project, a number of pages are already included. In fact, there is a master page, a home page, a contact page, and a page that shows information about the application. Pages are located inside the Views project subfolder and organized within subfolders. The logic for organizing pages is based on which controller a page responds to. For example, the HomeController class has the three actions: Index, About, and Contact. Therefore, the runtime expects to find three pages called Index.cshtml, About.cshtml, and Contact.cshtml inside a folder called Home, whose name is taken from the controller name without the Controller literal. This also affects the URL the application exposes to reach a page. For example, www.myapp.com/home will point to the HomeIndex.cshtml page, www.myapp.com/home/contact will point to the HomeContact.cshtml page, and so on. This is something that you must keep in mind for the next steps and, more generally, every time you work with views and controllers.

Additionally, you can find a Shared subfolder that contains two shared pages: _Layout.cshtml, which you may think of as a master page, and Error.cshtml, a page that displays common error messages. In summary, there should be a page for each action in a controller. The VisionController class has two actions, Vision and Index. As an implication, you must create a subfolder called Vision under the Views folder and add two new pages called Index.cshtml and Vision.cshtml. Visual Studio 2017 for Mac has an item template for .cshtml files, so you must select the MVC View Layout Page template in the ASP.NET Core category, as shown in Figure 10-7.

Figure 10-7. Adding a .cshtml file

Let’s start with the markup code of the Index.cshtml page, which is the main page for image analysis (you will see how to include a shortcut in the master page in a few moments). The code is as follows:

@{
    ViewData["Title"] = "Select an image for analysis";
}
<h2>@ViewData["Title"]</h2>
<h3>@ViewData["Message"]</h3>

<div class="row">
    <div class="col-md-12">
        <form asp-action="Vision" enctype="multipart/form-data">
            <div class="form-horizontal">
                <div class="form-group">
                    <label for="file">Image</label>
                    <input type="file" name="file" id="file" class="form-control">
                    <p class="help-block">
                     Images must be up to 4 megabytes and greater than 50x50</p>
                </div>
                <div class="form-group">
                    <input type="submit" value="Upload" class="btn btn-primary" />
                </div>
            </div>
        </form>
    </div>
</div>

With .cshtml files , you can embed C# expressions and statements. In the previous code, you can see how the ViewData property from the controller is embedded in the markup. C# expressions must be preceeded by the @ symbol; also, code snippets that contain only C# expressions (and no HTML tags) must be enclosed within curly braces. In the Index page, the Title key in the ViewData dictionary is assigned with a string, and this is pure C# code. In the h2 tag, instead of hard-coding a string, the value of the ViewData["Title"] is displayed by binding such a property value. In the h3 tag, the text that will be displayed instead comes from the value of the ViewData["Message"] property, which is assigned by the controller at runtime. A group of controls is then provided in the form element. Notice how an action in the backing controller is associated with the asp-action attribute. If you are familiar with HTML, the code will be simple to you. In fact, at its core, it contains an input control that allows you to select a file from disk by assigning the type attribute with the file value. The other input control, with type submit, allows you to upload the selected file to the server. The rest of the code is easy. The next page to write is the Vision.cshtml one. This will be displayed once the controller receives a response from the Computer Vision API service and saves the image information into the database. So, this page will display the original image, the result of the Computer Vision analysis, and a table that shows the list of images that were previously analyzed. The following is the code for the page:

@model IEnumerable<CrossComputerVision.Models.ImageData>

@{
    ViewData["Title"] = "Image list";
}

<h2>@ViewData["Title"]</h2>
<div class="row">
    <div class="col-md-12">
        <h4>Original Image</h4>
        <img src="@ViewData["originalImage"]" width="100" height="100"/>
    </div>
</div>

<div class="row">
    <div class="col-md-12">
        <h4>Result</h4>
        <label>@ViewData["result"]</label>
    </div>
</div>

<div class="row">
    <table class="table">
        <tr>
            <th>Image</th>
            <th>Result</th>
            <th>Date</th>
        </tr>
        @foreach (var item in Model)
        {
            <tr>
                <td>
                    @Html.DisplayFor(modelItem => item.ImageName)
                </td>
                <td>
                    @Html.DisplayFor(modelItem => item.DetectionResult)
                </td>
                <td>
                    @Html.DisplayFor(modelItem => item.TimeStamp)
                </td>
            </tr>
        }
    </table>
</div>

The @model expression determines the .NET type of the data model bound to this page. This implies that you can bind C# expressions to HTML controls, which provides a lot of flexibility when designing pages.

In this case, controllers can pass to the page any collection that implements the IEnumerable interface and whose type parameter is ImageData such as the List. This data source is referenced in the HTMK markup via the Model property of the bound controller. This allows for iterating the collection with a foreach loop and for using the Html.DisplayFor helper that shows the bound data in the appropriate control depending on the type of the property passed with a lambda expression. This is useful with controls of type table, where you simply define column headers with the th tag, and then you can populate the columns by simply iterating the model with limited effort on your part. Notice how the img control has an explicit size and how the image analysis result will be displayed based on the value of the ViewData["Message"] property assigned at runtime by the controller, once it receives a response from the Computer Vision service. The last step is to add a shortcut to the VisionIndex.cshtml page in the application’s master page. To accomplish this, open the Shared\_Layout.cshtml file and add the line highlighted in bold:

<li><a asp-area="" asp-controller="Home" asp-action="Index">Home</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="About">About</a></li>
<li><a asp-area="" asp-controller="Home" asp-action="Contact">Contact</a></li>
<li><a asp-area="" asp-controller="Vision" asp-action="Index">Computer Vision</a></li>                  

This way, in the application home page there will be a new item called Computer Vision that points to the Index action in the Vision controller and that therefore will launch the VisionIndex.cshtml page. After this much work, you are ready to debug your first ASP.NET Core web application based on MVC.