Understanding the ASP.NET 5 Project Template and Related Files
A typical website contains a number of different files including web pages, class files, scripts, style sheets, configuration files, images, JavaScript client libraries, and more. Visual Studio works to keep these many files organized and grouped together so that you may focus on building your site. As an example, the ASP.NET 5 Web Site project template (created as shown back in Figure 17.2) has a default structure in Solution Explorer, including many special directories and file types. Figure 17.3 show the default structure and contents when using this template.
FIGURE 17.3 The ASP.NET 5 Web Site template contains folders, client libraries, configuration, and related structure for your website.
The many folders, special directories, configuration files, and web pages come together at runtime to provide a response to a user’s browser request. The following walks you through the key elements shown in Figure 17.3. Later in the chapter we walk through using these file types and directories to build an actual site.
wwwroot and Other Significant Directories
An ASP.NET website groups files using conventions and “special” directories (as shown in Figure 17.3). The regular folders such as Controllers, Models, and Views allow you to easily organize your code. The special directories represent a convention on how ASP.NET works and where it stores required items that are outside your project code.
One such directory is wwwroot, which is new to ASP.NET 5. It represents the actual root of your site as in http://mydomain/. It is used for the static files in your project, such as images, style sheets, JavaScript files, and the like. Putting static files in this common location makes referencing them easier; it also allows ASP.NET to serve these static files directly to clients (knowing it does not need to process or compile them).
The wwwroot of the default ASP.NET 5 Web Site template already contains your style sheet (css/site.css) as well as key client-side JavaScript frameworks such as Bootstrap and jQuery in the lib folder (placed there at compile time by a Gulp task). Other items will end up in the wwwroot folder, too. This includes processed CSS files, minified JavaScript, optimized images, compiled TypeScript to JavaScript, and more. Typically, the source for these items sits outside of wwwroot while you create, edit, and refine them. You then write tasks (using tools like Gulp, as you will see shortly) to process or compile these files and put the results in the wwwroot for serving to clients.
For example, you may have a JavaScript library that you have written yourself for your specific website. You would keep that code outside of the wwwroot while you work to edit and refine it over time. When it is time to run (or release) the code, you would want to optimize it for faster processing through a process called minifying. This takes the JavaScript file and removes whitespace (among other things) to make it process much faster. To do so, you would write a Gulp task to tell it to minify your code at compile time and push the results to wwwroot.
ASP.NET includes a number of special folders like wwwroot. The following provides a reference for the many directories that are used as convention to define an ASP.NET website:
Properties—Used to define settings and properties for your application. This folder contains a class, AppSettings. Here you can define properties that are useful across your site.
References—Controls the other .NET libraries referenced by your application. By default, the ASP.NET 5 templates reference both the full DNX and the DNX Core. References are typically managed through NuGet but could also be a project specific reference or a connected service reference.
wwwroot—The root of your website. Used for containing and serving up static files. (See earlier discussion.)
Dependencies—Groups the client-side libraries that your application depends on and their build tasks. These dependencies are managed in the bower.json configuration file; the tasks are managed in the Task Runner Explorer. See the upcoming section, “ASP.NET 5 Dependencies and Package Managers.”
Compiler—Store compilation configuration code. In the current release, this is a file that enables pre-compilation of Razor views to cut down on compile time for the first use.
Migrations—Works with the Entity Framework and contains code used to migrate changes and updates to your database as your code evolves.
The MVC folders (Models, Views, and Controllers)—Folders for grouping the key code items in your website. The Models folder contains class files that represent your data model. The Views folder is where you store .cshtml markup pages for rendering your user interface. The Controllers folder is used for writing code to intercept web requests and return the response (usually by working with Models and Views). See the upcoming section, “Creating a Web Application with ASP.NET 5/MVC 6.”
Project Files
Numerous files and file types define a typical ASP.NET website. You need only look at the Add New Item dialog (right-click Website in Solution Explorer and choose Add, New Item) to see the many file types you can add to your site. There are files that you use often, such as web views/partial views and classes. You might also work with configuration files and write a lot of JavaScript. Table 17.1 lists some of the more common files that might exist in any given ASP.NET 5/MVC 6 web application. The table includes the given item template name (from the Add New Item dialog), the file extension, and a short description.
The Configuration Files
ASP.NET 5 introduces the JSON configuration files. JSON stands for JavaScript Simple Object Notation and is used by developers to exchange data. It replaced XML for most HTTP web services because XML is viewed as too large and complex. Microsoft has now replaced the .config files that were based on XML with new .json files for doing configuration. The section that follows (“ASP.NET 5 Dependencies and Package Managers”) illustrates working with and editing these various configuration files. The following provides a reference for some of the many .json configuration files you will encounter in an ASP.NET 5.0 site:
global.json—Used to define settings at the solution level (file is inside the Solution Items folder); it also allows for project-to-project references.
project.json—This is the primary configuration file for your project. Here you define the version of the framework on which your site depends, other dependent packages (from NuGet), your intended web host, your web root, client package managers, and more.
config.json—A configuration file you can use for your project configuration items, such as database connection strings. This relies on Microsoft.Framework.ConfigurationModel.Json for reading values from your configuration file.
bower.json—Used to manage the client-side JavaScript packages on which your site might depend, such as jQuery and Bootstrap.
package.json—Configures NPM (Node Package Manager) packages. NPM is another JavaScript client-side library package manager. It is used for libraries like Node, AngularJS, and Gulp.
gulpfile.js—A JavaScript file used by Gulp to define and configure automated processing tasks. Gulp tasks are used for processing client files for deployment, such as minifying JavaScript or processing Sass into CSS.
Startup.cs—This is not a .json file but an actual class file that is compiled with your application. That said, the class file is used to define various configuration elements through code. You use Startup.cs to configure the ASP.NET request pipeline. This includes defining your application host, configuring application services (such as MVC), setting URL routing conventions, and more.
Given that so many of the configuration files are written as JSON, it is important that you have a feel for how this notation works. At its most basic level, you define an object using curly brackets {}. Inside the brackets you define properties of that object using name and value pairs separated by a colon, as in "name": "value". Each of these properties could also define another object following the same semantics. Each property is separated by a comma. The following shows a basic example of a customer object in JSON notation. Notice the email property inside the customer contact object; its values are defined by an array enclosed with square brackets ([ ]).
{
"customer": {
"name": "Jane Smith",
"id": 123456,
"age": 38,
"contact": {
"street": "One Microsoft Way",
"city": "Redmond",
"state": "Washington",
"postalCode": "98052",
"email": [
"[email protected]",
"[email protected]"
]
}
}
}