Choosing a Code Editor

Microsoft provides a choice of tools for ASP.NET Core development: Visual Studio and Visual Studio Code. Visual Studio is the traditional development environment for .NET applications, and it offers an enormous range of tools and features for developing all sorts of applications. But it can be resource-hungry and slow, and some of the features are so determined to be helpful they get in the way of development.

Visual Studio Code is a light-weight alternative that doesn’t have the bells and whistles of Visual Studio but is perfectly capable of handling ASP.NET Core development.

All the examples in this book include instructions for both editors, and both Visual Studio and Visual Studio Code can be used without charge, so you can use whichever suits your development style.

If you are new to .NET Core development, then start with Visual Studio. It provides more structured support for creating the different types of files used in ASP.NET Core development, which will help ensure you get the expected results from the code examples.

Installing Visual Studio

ASP.NET Core 3 requires Visual Studio 2019. I use the free Visual Studio 2019 Community Edition, which can be downloaded from www.visualstudio.com. Run the installer, and you will see the prompt shown in Figure 2-1.

Click the Continue button, and the installer will download the installation files, as shown in Figure 2-2.

When the installer files have been downloaded, you will be presented with a set of installation options, grouped into workloads. Ensure that the “ASP.NET and web development” workload is checked, as shown in Figure 2-3.

Select the “Individual components” section at the top of the window and ensure the SQL Server Express 2016 LocalDB option is checked, as shown in Figure 2-4. This is the database component that I will be using to store data in later chapters.

Click the Install button, and the files required for the selected workload will be downloaded and installed. To complete the installation, a reboot is required, as shown in Figure 2-5.

Installing the .NET Core SDK

The Visual Studio installer will install the .NET Core Software Development Kit (SDK), but it may not install the version required for the examples in this book. Go to https://dotnet.microsoft.com/download/dotnet-core/3.1 and download the installer for version 3.1.1 of the .NET Core SDK, which is the long-term support release at the time of writing. Run the installer; once the installation is complete, open a new PowerShell command prompt from the Windows Start menu and run the command shown in Listing 2-1, which displays a list of the installed .NET Core SDKs.

dotnet --list-sdks

Listing 2-1.

Listing the Installed SDKs

Here is the output from a fresh installation on a Windows machine that has not been used for .NET Core:

3.1.101 [C:Program Filesdotnetsdk]

If you have been working with different versions of .NET Core, you may see a longer list, like this one:

2.1.401 [C:Program Filesdotnetsdk]

2.1.502 [C:Program Filesdotnetsdk]

2.1.505 [C:Program Filesdotnetsdk]

2.1.602 [C:Program Filesdotnetsdk]

2.1.802 [C:Program Filesdotnetsdk]

3.0.100 [C:Program Filesdotnetsdk]

3.1.100 [C:Program Filesdotnetsdk]

3.1.101 [C:Program Filesdotnetsdk]

Regardless of how many entries there are, you must ensure there is one for the 3.1.1xx version, where the last two digits may differ.

Installing Visual Studio Code

If you have chosen to use Visual Studio Code, download the installer from https://code.visualstudio.com. No specific version is required, and you should select the current stable build. Run the installer and ensure you check the Add to PATH option, as shown in Figure 2-6.

Installing the .NET Core SDK

The Visual Studio installer does not include the .NET Core SDK, which must be installed separately. Go to https://dotnet.microsoft.com/download/dotnet-core/3.1 and download the installer for version 3.1.1 of the .NET Core SDK, which is the long-term support release at the time of writing. Run the installer; once the installation is complete, open a new PowerShell command prompt from the Windows Start menu and run the command shown in Listing 2-2, which displays a list of the installed .NET Core SDKs.

dotnet --list-sdks

Listing 2-2.

Listing the Installed SDKs

Here is the output from a fresh installation on a Windows machine that has not been used for .NET Core:

3.1.101 [C:Program Filesdotnetsdk]

If you have been working with different versions of .NET Core, you may see a longer list, like this one:

2.1.401 [C:Program Filesdotnetsdk]

2.1.502 [C:Program Filesdotnetsdk]

2.1.505 [C:Program Filesdotnetsdk]

2.1.602 [C:Program Filesdotnetsdk]

2.1.802 [C:Program Filesdotnetsdk]

3.0.100 [C:Program Filesdotnetsdk]

3.1.100 [C:Program Filesdotnetsdk]

3.1.101 [C:Program Filesdotnetsdk]

Regardless of how many entries there are, you must ensure there is one for the 3.1.1xx version, where the last two digits may differ.

Installing SQL Server LocalDB

The database examples in this book require LocalDB, which is a zero-configuration version of SQL Server that can be installed as part of the SQL Server Express edition, which is available for use without charge from https://www.microsoft.com/en-in/sql-server/sql-server-downloads. Download and run the Express edition installer and select the Custom option, as shown in Figure 2-7.

Once you have selected the Custom option, you will be prompted to select a download location for the installation files. Click the Install button, and the download will begin.

When prompted, select the option to create a new SQL Server installation, as shown in Figure 2-8.

Work through the installation process, selecting the default options as they are presented. When you reach the Feature Selection page, ensure that the LocalDB option is checked, as shown in Figure 2-9. (You may want to uncheck the options for R and Python, which are not used in this book and take a long time to download and install.)

On the Instance Configuration page, select the “Default instance” option, as shown in Figure 2-10.

Continue to work through the installation process, selecting the default values. Once the installation is complete, install the latest cumulative update for SQL Server. At the time of writing, the latest update is available at https://support.microsoft.com/en-us/help/4527377/cumulative-update-18-for-sql-server-2017, although newer updates may have been released by the time you read this chapter.

Caution

It can be tempting to skip the update stage, but it is important to perform this step to get the expected results from the examples in this book. As an example, the base installation of SQL Server has a bug that prevents LocalDB from creating database files, which will cause problems when you reach Chapter 7.

Creating an ASP.NET Core Project

The most direct way to create a project is to use the command line, although Visual Studio provides a wizard system that I demonstrate in Chapter 4. Open a new PowerShell command prompt from the Windows Start menu, navigate to the folder where you want to create your ASP.NET Core projects, and run the commands shown in Listing 2-3.

The first command creates a folder named FirstProject and adds to it a file named global.json, which specifies the version of .NET Core that the project will use; this ensures you get the expected results when following the examples. The second command creates a new ASP.NET Core project. The .NET Core SDK includes a range of templates for starting new projects, and the mvc template is one of the options available for ASP.NET Core applications. This project template creates a project that is configured for the MVC Framework, which is one of the application types supported by ASP.NET Core. Don’t be intimidated by the idea of choosing a framework, and don’t worry if you have not heard of MVC—by the end of the book, you will understand the features that each offers and how they fit together.

Opening the Project Using Visual Studio

Start Visual Studio and click the “Open a project or solution” button, as shown in Figure 2-11.

Navigate to the FirstProject folder, select the FirstProject.csproj file, and click the Open button. Visual Studio will open the project and display its contents in the Solution Explorer window, as shown in Figure 2-12. The files in the project were created by the project template.

Choosing a Browser

Visual Studio will open a browser window automatically when the project is run. To select the browser that is used, click the small arrow to the right of the IIS Express drop-down and select your preferred browser from the Web Browser menu, as shown in Figure 2-13. I use Google Chrome throughout this book.

Opening the Project with Visual Studio Code

Start Visual Studio Code and select FIle ➤ Open Folder. Navigate to the FirstProject folder and click the Select Folder button. Visual Studio Code will open the project and display its contents in the Explorer pane, as shown in Figure 2-14. (The default dark theme used in Visual Studio Code doesn’t show well on the page, so I have changed to the light theme for the screenshots in this book.)

Additional configuration is required the first time you open a .NET Core project in Visual Studio Code. The first step is to click the Startup.cs file in the Explorer pane. This will trigger a prompt from Visual Studio Code to install the features required for C# development, as shown in Figure 2-15. If you have opened a C# project before, you will see a prompt that offers to install the required assets, also shown in Figure 2-15.

Click the Install or Yes button, as appropriate, and Visual Studio Code will download and install the features required for .NET Core projects.

Running the ASP.NET Core Application

The template creates a project that contains everything needed to build and run the application. Select Start Without Debugging from the Debug menu, and Visual Studio will compile and start the example application and then open a new browser window to send the application an HTTP request, as shown in Figure 2-17. (If you don’t see the Start Without Debugging item in the Debug menu, then click the Startup.cs file in the Solution Explorer window and check the menu again.)

If you are using Visual Studio Code, select Run Without Debugging in the Debug menu. Since this is the first time the project has been started, you will be prompted to select an execution environment. Select the .NET Core option, as shown in Figure 2-16.

Visual Studio Code will create a launch.json file that contains the startup settings for the project and that you can ignore for this book. Select Run Without Debugging from the Debug menu again, and Visual Studio Code will compile the project, start executing the application, and open a new browser window, as shown in Figure 2-17.

Once the application has started, you will need to open a new browser window and request http://localhost:5000, which will produce the response shown in Figure 2-17.

When you are finished, close the browser window that Visual Studio opened. If you are using Visual Studio Code, you click the stop button displayed in the window that pops up over the code editor. If you started the application from the command line, then use Control+C to stop execution.

Understanding Endpoints

In an ASP.NET Core application, incoming requests are handled by endpoints. The endpoint that produced the response in Figure 2-17 is an action, which is a method that is written in C#. An action is defined in a controller, which is a C# class that is derived from the Microsoft.AspNetCore.Mvc.Controller class, the built-in controller base class.

Each public method defined by a controller is an action, which means you can invoke the action method to handle an HTTP request. The convention in ASP.NET Core projects is to put controller classes in a folder named Controllers, which was created by the template used to set up the project in Listing 2-3.

The project template added a controller to the Controllers folder to help jump-start development. The controller is defined in the class file named HomeController.cs. Controller classes contain a name followed by the word Controller, which means that when you see a file called HomeController.cs, you know that it contains a controller called Home, which is the default controller that is used in ASP.NET Core applications.

Tip

Don’t worry if the terms controller and action don’t make immediate sense. Just keep following the example, and you will see how the HTTP request sent by the browser is handled by C# code.

Find the HomeController.cs file in the Solution Explorer or Explorer pane and click it to open it for editing. You will see the following code:

using System;

using System.Collections.Generic;

using System.Diagnostics;

using System.Linq;

using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;

using Microsoft.Extensions.Logging;

using FirstProject.Models;

namespace FirstProject.Controllers {

    public class HomeController : Controller {

        private readonly ILogger<HomeController> _logger;

        public HomeController(ILogger<HomeController> logger) {

            _logger = logger;

        }

        public IActionResult Index() {

            return View();

        }

        public IActionResult Privacy() {

            return View();

        }

        [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None,

             NoStore = true)]

        public IActionResult Error() {

            return View(new ErrorViewModel { RequestId = Activity.Current?.Id

                ?? HttpContext.TraceIdentifier });

        }

    }

}

Using the code editor, replace the contents of the HomeController.cs file so that it matches Listing 2-5. I have removed all but one of the methods, changed the result type and its implementation, and removed the using statements for unused namespaces.

using Microsoft.AspNetCore.Mvc;

namespace FirstProject.Controllers {

    public class HomeController : Controller {

        public string Index() {

            return "Hello World";

        }

    }

}

Listing 2-5.

Changing the HomeController.cs File in the Controllers Folder

The result is that the Home controller defines a single action, named Index. These changes don’t produce a dramatic effect, but they make for a nice demonstration. I have changed the method named Index so that it returns the string Hello World. Run the project again by selecting Start Without Debugging or Run Without Debugging from the Debug menu.

The browser will make an HTTP request to the ASP.NET Core server. The configuration of the project created by the template in Listing 2-5 means the HTTP request will be processed by the Index action defined by the Home controller. Put another way, the request will be processed by the Index method defined by the HomeController class. The string produced by the Index method is used as the response to the browser’s HTTP request, as shown in Figure 2-18.

Understanding HTML Rendering

The output from the previous example wasn’t HTML—it was just the string Hello World. To produce an HTML response to a browser request, I need a view, which tells ASP.NET Core how to process the result produced by the Index method into an HTML response that can be sent to the browser.

Creating and Rendering a View

The first thing I need to do is modify my Index action method, as shown in Listing 2-6. The changes are shown in bold, which is a convention I follow throughout this book to make the examples easier to follow.

using Microsoft.AspNetCore.Mvc;

namespace FirstProject.Controllers {

    public class HomeController : Controller {

        public ViewResult Index() {

            return View("MyView");

        }

    }

}

Listing 2-6.

Rendering a View in the HomeController.cs File in the Controllers Folder

When I return a ViewResult object from an action method, I am instructing ASP.NET Core to render a view. I create the ViewResult by calling the View method, specifying the name of the view that I want to use, which is MyView. If you run the application, you can see ASP.NET Core trying to find the view, as shown by the error message displayed in Figure 2-19.

This is a helpful error message. It explains that ASP.NET Core could not find the view I specified for the action method and explains where it looked. Views are stored in the Views folder, organized into subfolders. Views that are associated with the Home controller, for example, are stored in a folder called Views/Home. Views that are not specific to a single controller are stored in a folder called Views/Shared. The template used to create the project added the Home and Shared folders automatically and added some placeholder views to get the project started.

If you are using Visual Studio, right-click the Views/Home folder in the Solution Explorer and select Add ➤ New Item from the popup menu. Visual Studio will present you with a list of templates for adding items to the project. Locate the Razor View item, which can be found in the ASP.NET Core ➤ Web ➤ ASP.NET section, as shown in Figure 2-20. Set the name of the new file to MyView.cshtml and click the Add button. Visual Studio will add a file named MyView.cshtml to the Views/Home folder and will open it for editing. Replace the contents of the file with those shown in Listing 2-7.

Visual Studio Code doesn’t provide item templates. Instead, right-click the Views/Home folder in the file explorer pane and select New File from the popup menu. Set the name of the file to MyView.cshtml and press Return. The file will be created and opened for editing. Add the content shown in Listing 2-7.

Tip

It is easy to end up creating the view file in the wrong folder. If you didn’t end up with a file called MyView.cshtml in the Views/Home folder, then either drag the file into the correct folder or delete the file and try again.

@{

    Layout = null;

}

<!DOCTYPE html>

<html>

<head>

    <meta name="viewport" content="width=device-width" />

    <title>Index</title>

</head>

<body>

    <div>

        Hello World (from the view)

    </div>

</body>

</html>

Listing 2-7.

The Contents of the MyView.cshtml File in the Views/Home Folder

The new contents of the view file are mostly HTML. The exception is the part that looks like this:

...

@{

    Layout = null;

}

...

This is an expression that will be interpreted by Razor, which is the component that processes the contents of views and generates HTML that is sent to the browser. Razor is a view engine, and the expressions in views are known as Razor expressions.

The Razor expression in Listing 2-7 tells Razor that I chose not to use a layout, which is like a template for the HTML that will be sent to the browser (and which I describe in Chapter 22). To see the effect of creating the view, stop ASP.NET Core if it is running and select Start Without Debugging (for Visual Studio) or Run Without Debugging (for Visual Studio Code) from the Debug menu. A new browser window will open and produce the response shown in Figure 2-21.

When I first edited the Index action method, it returned a string value. This meant that ASP.NET Core did nothing except pass the string value as is to the browser. Now that the Index method returns a ViewResult, Razor is used to process a view and render an HTML response. Razor was able to locate the view because I followed the standard naming convention, which is to put view files in a folder whose name matched the controller that contains the action method. In this case, this meant putting the view file in the Views/Home folder, since the action method is defined by the Home controller.

I can return other results from action methods besides strings and ViewResult objects. For example, if I return a RedirectResult, the browser will be redirected to another URL. If I return an HttpUnauthorizedResult, I can prompt the user to log in. These objects are collectively known as action results. The action result system lets you encapsulate and reuse common responses in actions. I’ll tell you more about them and explain the different ways they can be used in Chapter 19.

Adding Dynamic Output

The whole point of a web application is to construct and display dynamic output. The job of the action method is to construct data and pass it to the view so it can be used to create HTML content based on the data values. Action methods provide data to views by passing arguments to the View method, as shown in Listing 2-8. The data provided to the view is known as the view model.

using Microsoft.AspNetCore.Mvc;

using System;

namespace FirstProject.Controllers {

    public class HomeController : Controller {

        public ViewResult Index() {

            int hour = DateTime.Now.Hour;

            string viewModel = hour < 12 ? "Good Morning" : "Good Afternoon";

            return View("MyView", viewModel);

        }

    }

}

Listing 2-8.

Providing a View Model in the HomeController.cs File in the Controllers Folder

The view model in this example is a string, and it is provided to the view as the second argument to the View method. Listing 2-9 updates the view so that it receives and uses the view model in the HTML it generates.

@model string

@{

    Layout = null;

}

<!DOCTYPE html>

<html>

<head>

    <meta name="viewport" content="width=device-width" />

    <title>Index</title>

</head>

<body>

    <div>

        @Model World (from the view)

    </div>

</body>

</html>

Listing 2-9.

Using a View Model in the MyView.cshtml File in the Views/Home Folder

The type of the view model is specified using the @model expression, with a lowercase m. The view model value is included in the HTML output using the @Model expression, with an uppercase M. (It can be difficult at first to remember which is lowercase and which is uppercase, but it soon becomes second nature.)

When the view is rendered, the view model data provided by the action method is inserted into the HTML response. Select Start Without Debugging (using Visual Studio) or Run Without Debugging (using Visual Studio Code), and you will see the output shown in Figure 2-22 (although you may see the afternoon greeting if you are following this example after midday).

Summary

In this chapter, I explained how to get set up for ASP.NET Core development by installing Visual Studio or Visual Studio Code and the .NET Core SDK. I showed you how to create a simple project and briefly explained how the endpoint, the view, and the URL routing system work together. In the next chapter, I show you how to create a simple data-entry application.