ASP.NET 5 Project Basics

4.77 (13 votes)

When you create a new ASP.NET web application using the Web Application template, you are presented with a raft of new folders and files in a completely new structure. This article is the first in a series that attempts to demystify the new structure and the role that some of these files play. The article series starts with the Empty template and adds the various files that you might see in the web application template progressively to illustrate their purpose. This article uses Visual Studio 2105 RTM and ASP.NET 5 Beta 6. It will be updated in line with future releases.

Solution and Project structure

If you are familiar with previous versions of ASP.NET, the change in solution and project structure in ASP.NET 5 is quite considerable.

MVC6 with EF7

The role of the solution is the same as in previous versions of Visual Studio: it is a container for organising the items required by your application. It includes projects, build configurations and so on. JSON is the preferred format for configuration files in other modern web development frameworks, so it has been chosen instead of XML as the default format for configuration files in ASP.NET 5. So the solution is defined by the contents of a global.json file (although VS 2015 still produces .sln files):

  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-beta6"

VS2015 specifies two locations for projects in the solution: src and test. The src project contains the actual application while the test project contains any tests and will be generated automatically if you selected the option to include tests when creating the original application. The image above shows an application generated without this option selected. The file also specifies that this application will make use of the beta 6 version of ASP.NET 5. You can have multiple applications running on the same machine, each one targeting a different version of ASP.NET 5. Now that it is open source and free from the shackles of the rest of the .NET framework, it is anticipated that the release cycle for new major and minor versions of ASP.NET will be a lot more frequent than with previous versions.

The NuGet.config file is an XML file that contains details of the location of the NuGet feed from where packages used in the application will be retrieved.

<?xml version="1.0" encoding="utf-8"?>
    <!--To inherit the global NuGet package sources remove the <clear/> line below -->
    <clear />
    <add key="" value="" />


When expanded, the References node provides a visual tree-style representation of the frameworks that the project targets, and the server-side references ( .NET assemblies, NuGet packages, other projects) for each one.

MVC6 With EF7

The project above targets .NET 4.5.1. It also targets the new .NET Core framework (DNX Core 5.0), a lightweight cross platform and cloud optimised framework introduced as part of ASP.NET 5. As you add further references to server-side packages or libraries that your application depends on, they will appear here.

The wwwroot folder

The wwwroot folder is new in ASP.NET 5. It is the location for browsable static files, such as images, style sheets and JavaScript files. Source code must be located outside of the wwwroot folder. Also, if you have static files that require some form of processing before you make them available - for example, PDF files that should only be available to authenticated users - you would not place them in the wwwroot folder.


This node is like the References node, except that it features client-side dependencies. In previous versions of Visual Studio, you were expected to use the NuGet package manager to obtain client-side libraries such as jQuery, BootStrap. Angular and so on. Visual Studio 2015 features first class support for framework agnostic package managers and tools such as Bower and NPM. While you can still use NuGet for your client-side dependencies, you also have the option to get to know and use the tools that the rest of the development world are using. The next article in this series will focus on installing and using these tools.

The project.json file

This file is used to manage project settings and server side dependencies. It largely replaces the web.config file from previous versions of ASP.NET. The default file contains the following:

  "webroot": "wwwroot",
  "version": "1.0.0-*",

  "dependencies": {
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta6",
    "Microsoft.AspNet.Server.WebListener": "1.0.0-beta6"

  "commands": {
    "web": "Microsoft.AspNet.Hosting --config hosting.ini"

  "frameworks": {
    "dnx451": { },
    "dnxcore50": { }

  "publishExclude": [
  "exclude": [

The first section specifies which folder should act as the webroot. By default, it is the wwwroot folder covered earlier. If you change the name of this folder to another one in the solution, Visual Studio will reflect that change by applying the same globe icon in Solution Explorer for your new folder choice that it currently uses for the wwwroot folder.

The content of the dependencies section is reflected in Dependencies node in Solution Explorer. This is where you can add and remove NuGet packages. This section enjoys full IntelliSense support - the responsiveness of which depends on your Internet connection as the source for the IntelliSense matches is the NuGet feed specified in the NuGet.config file.

The commands section contains any commands you want to execute against dnx.exe, which is the .NET Execution Environment (DNX). Each entry represents the name of the command which acts as a kind of alias for the assembly that dnx.exe should attempt to load, together with any parameters that should be passed to the assembly. The "web" command included by default starts up a rudimentary web server (Microsoft.AspNet.Server.WebListener found in the Microsoft.Asp.Net.Hosting assembly) enabling hosting outside of IIS. As well as using a command prompt to execute commands, they are available in the Run menu in Visual Studio:

MVC6 With EF7

The arguments passed to the command spcify that the configuration for the simple web server can be found in a file called hosting.ini, which is also included as part of the project. This is a simple text-based config file with the following content:



The frameworks section shows the frameworks that the application is designed to target. This is depicted visually in the References node in Solution Explorer as mentioned earlier. If you comment out the dnxcore50 entry in project.json, you will see (Restoring...) appear next to the References node as the entry for DNX Core 50 disappears:

MVC6 With EF7

Any framework-specific dependencies are listed in the braces that follow the framework entry.

The publishExclude section is for resources that should be excluded from the publishing process. Globbing syntax is supported for specifying wildcard matches when indicating the resource types that should be excluded. Items in the exclude section are excluded from compilation. The wwwroot folder is excluded from compilation as it should only contain static files. Two other folders, node_modules and bower_components have been excluded from publishing and compilation, but do not exist - yet. These will get created in the next tutorial when I look at managing client-side dependencies.


The final file of interest is the Startup.cs file. This is the entry point for the bootstrapping your web application (performing initial configuration tasks). It will be familiar to those who have worked with OWIN-based applications in earlier versions of ASP.NET. ASP.NET 5 applications are designed to be composable, based on an opt-in policy, where you choose only the components and services required for your application. This is in contrast to previous versions of ASP.NET, where everything you could conceivably need was crammed in to System.Web, and you had to depend on that regardless. The Startup class is where you specify the modules that your application requires. The default code is minimal:

public class Startup
    public void ConfigureServices(IServiceCollection services)

    public void Configure(IApplicationBuilder app)
        app.Run(async (context) =>
            await context.Response.WriteAsync("Hello World!");

There are two methods: ConfigureServices and Configure. The ConfigureServices method is called first by the ASP.NET runtime and acts to register services (components) with the built-in dependency injection system. Examples of services include MVC itself, ASP.NET Identity and Entity Framework. The Configure method is where you register components with the Request pipeline in the order in which they should be called. The only thing that has been added to the request pipeline in the Empty template is a delegate that writes "Hello World!" to the Response.

Running the application

At this stage, you have not added anything to your ASP.NET 5 application. However, it will do something as determined by the delegate in the Configure method. If you run the application without debugging by pressing Ctrl+F5, your default browser should appear with "Hello World!" in it:

MVC6 With EF7


Now navigate to the Startup.cs file and change the text in the delegate to say "Goodbye World!"

app.Run(async (context) =>
    await context.Response.WriteAsync("Goodbye World!");

Save the change and switch back to the browser. Hit F5 or click the Refresh button. The display should update to show the change you just made to the source code.

MVC6 With EF7 


In previous versions of ASP.NET, you had to recompile your code to get changes to source code to take effect. Visual Studio 2015 makes use of a new compiler, Roslyn, which detects changes to source code files and recompiles the code in memory. This experience is very similar to the one enjoyed by users of dynamic languages such as PHP, Ruby, Python, VBScript etc and enables you to be more productive during development because you don't have to keep waiting around for your code to build before you can test changes to source code.


This article introduced the new project structure employed by ASP.NET 5 applications and explored the main files and their purpose. It also looked at how the latest in compiler technology treats strongly typed source code as if it was a dynamic language processed on the fly to improve the developer experience.The next article in the series will take a look at how the management of client-side dependencies is catered for, using popular open source tools that have been integrated with the latest version of Visual Studio.


You might also like...

Date Posted:
Last Updated:
Posted by:
Total Views to date: 9953


- Manoj Kulkarni

Nice article. Very helpful.

- Fritz Mack

Super article, I have waited for.

- Parmod

For a new learner (Fresher) in ASP.NET
there is a issue
Fresher have to learn two types
of project structures , like old one with
web.config and new one with project.json etc.
should one learn old or New

- Mike


It depends on whether you are likely to work on MVC 5 or older projects. If you aren't you will only need to learn the new project structure.

Recent Comments

Pam 30/08/2017 11:30
In response to Sending Email in Razor Pages
Mike, RazorPages sound like a nice choice for somebody still working in ASP classic who wants to to...

Robby Robson 15/08/2017 00:43
In response to Routing in Razor Pages
Mike: great stuff. Now that .Core Standard 2.0 is formally out, how soon will you rewrite your book...

Satyabrata Mohapatra 28/07/2017 08:59
In response to Sending Email in Razor Pages
Bit off topic, but congratulation sir for your MVP award. You deserve it !!!...

Satyabrata Mohapatra 23/07/2017 16:43
In response to Razor Pages - The Elevator Pitch
@Dale Severin You can continue to build apps using web pages....

Satyabrata Mohapatra 23/07/2017 16:40
In response to Sending Email in Razor Pages
Thanks for sharing...learned a lot...

Gfw 22/07/2017 11:53
In response to Sending Email in Razor Pages
Question... Does System.Net.Mail support SSL?...

Dale Severin 20/07/2017 03:38
In response to Razor Pages - The Elevator Pitch
I work with razor web pages extensively. I appreciate the rapid development it permits me to I am as...

Obinna Okafor 14/07/2017 01:19
In response to Routing in Razor Pages
Thank you, Mike. Good post....

Satyabrata Mohapatra 11/07/2017 16:02
In response to Routing in Razor Pages
Very powerful routing system!!...

Cyrus 05/07/2017 03:41
In response to Razor Pages - Getting Started With The Preview
How can I trim packages and services as much as possible to use just razor pages? I don’t want to to...