Complete Guide to Setting Up ASP.NET 5 MVC 6 for Stand Alone and IIS Servers

If you haven’t heard about ASP.NET 5 MVC 6, you are in for a big surprise! It’s been a while I worked on ASP.NET project, and since I had the rare opportunity to dig in, I could not resist but catch up on the latest and greatest of ASP.NET. And boy was I in for a huge surprise (or a present)!

Evolution

Since the days of ASP.NET 2.0 and its WebForms revolution, a few more frameworks were introduced. Amongst many, here are a few notable ones: MVC, Web Pages, SignalR (Single Page Application), Web API.

The big surprise and the excitement was that ASP.NET is now at its 5th version, and with that, Microsoft is introducing the vNext initiative that will make ASP.NET finally independent of both the heavy, machine-wide .NET platform as well as Windows Operating System, and finally Cloud optimized.

Not only is ASP.NET 5 entirely deployed using NuGet, it has full support for both traditional .NET Framework, but also through exciting .NET Core 5, an open source implementation of the ASP.NET engine, allows realtime download of latest libraries from NuGet, and deployment of completely packaged versions of ASP.NET applications regardless of its different use of libraries or even .NET frameworks (side-by-side deployment). You are not yet surprised? Guess what. They will soon introduce Mac and Linux cores. Yes, there is the Mono project, but this is still very exciting to see that Microsoft is making all the right moves this time around ;-).

Last but not least, with ASP.NET 5, Microsoft is also introducing MVC 6 that will merge MVC, Web Pages, and Web API, to provide more simplified framework that will take advantage of all of the great benefits.

The Project

Enough with the introductions and let’s get into the guts of this beast!

My project had to provide a set of RESTful APIs, for vendors to access securely and provide realtime updates. The project had the following requirements:

• Force HTTPS (HTTP over SSL)
• Authenticate using username and password
• Only allow white-listed IP addresses
• Provide RESTful APIs for add, update, and delete
• Scale to 400 or more requests or transactions per second
• Access MS SQL Server Stored Procedures
• Be able to step through the code and debug

I knew that ASP.NET MVC was the choice of the framework since it provided routing. That was when I ran into ASP.NET vNext initiative, and the ASP.NET 5 MVC 6. But at the time of this writing, ASP.NET 5 MVC 6 is still in its infancy and many of its NuGet packages are still in beta. Even Visual Studio 2015 is in RC (Release Candidate).

Fortunately, Microsoft has finally released a real tool for community called Visual Studio Community that has pretty much all of the benefits of what Visual Studio has known for, such as Intellisense, automatic fetching of packages from NuGet, as well as, build and deployment to IIS Express, and finally publishing of the app to a directory or even to the cloud. So without further ado, here are the steps that I took to get my environment up and running.

The Basics

Before we get going, here are the basic tools that we will need to install:

• Install Powershell 4.0. If you are in a corporate environment like I am, you may need to briefly manually turn on the Windows Update service on your PC if it has been disabled. Make sure to download appropriate version. These days, it would be the 64-bit version.

• Download and install .NET 4.5.2 Framework

• Install DNVM (.NET Version Manager), which allows you to download and installs the appropriate DNX (.NET Execution environment). DNVM is installed with Visual Studio but it will be a good exercise to actually download and install this since either if you want to develop without Visual Studio or need to develop in Mac or Linux, you will need to get the DNVM setup. Run the following on the command prompt:

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "&{$Branch='dev';iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.ps1'))}"

• Upgrade DNX to stable version by typing:

dnvm upgrade

• Install x64 runtime in addition to the basic x86 runtime that gets installed as default so that your app can run on 64-bit IIS. Type the following:

dnvm install -r clr -arch x64 latest

• Install Core version as well if you are planning to use .NET Core 5 framework by entering:

(for 32bit) dnvm install -r coreclr -arch x86 latest
(for 64bit) dnvm install -r coreclr -arch x64 latest

• One thing to note is that, they do release latest versions, so if you have library issues, then run these commands again to upgrade your runtime to latest that has lots of bug fixes and supports that were not available on the previous versions.

• Finally, download and install Visual Studio Community

If you don’t have the luxury of having Visual Studio, then you can get Yeoman to setup the scaffolding for your ASP.NET 5 MVC 6 project. Here are the steps to setup Yeoman:

• Install node.js
• Install npm (NodeJS Package Manager)
• Add C:\Program Files\nodejs to PATH
• Install Yeoman by typing the following onto command prompt:

npm install -g yo grunt-cli generator-aspnet bower

Now, let’s make our first ASP.NET 5 MVC 6 app using Yeoman:

• Enter the following to command prompt: yo aspnet
• For application name, type: ToDoApi
• Select Empty Application

It should have now created a folder, ToDoApi, with all of the necessary ASP.NET 5 folders and codes.

Deploy as a Stand-Alone Web Server

Now that we have the scaffolding code for ASP.NET 5 MVC 6, we can actually run this app as a stand-alone using .NET Execution environment (dnu) by:

• Change into the directory: cd ToDoApi
• Run .NET Development Utility (NuGet) to get the latest library from NuGet that the code is referencing: dnu restore
• Build the code: dnu build
• Using .NET Execution environment, launch the stand-alone web server: dnx . web
• Finally, load http://localhost:5000 and when you see “Hello World”, you have successfully launched your first ASP.NET 5 MVC 6 app!

Isn’t this so exciting? You can actually deploy ASP.NET application without IIS! In fact, above steps are how you can deploy the app for Mac and Linux.

Deploy to Local IIS

Deploying a stand-alone web app is all cool, but that local web server doesn’t come with all of the benefits that IIS has through its interface. And often in an enterprise environment, where servers and IIS are managed by IT, I needed to make sure that I can deploy my web  apps on an IIS Server. Here are the steps I took to successfully deploy the basic ASP.NET 5 MVC 6 app to my local IIS:

• On IIS, create a website
• Change its Application Pool account to .NET 4 Framework
• On the root of the project folder (TodoApi), publish the code by running:

dnu publish --runtime dnx-clr-win-x64.1.0.0-beta4

• Note that I’m using clr-win and x64 (64-bit) which I installed previously. If you are not sure of the exact name of the runtime, you can enter “dnvm list” to see all of the runtime versions installed on your PC.
• Copy files/folders from bin\output to the website root
• Map the website to wwwroot subfolder and not the root where approot folder exists, so that .NET framework 4 can access approot to load all of the necessary DLLs but serve up the content from wwwroot
• Minor tweaks on deployed code itself is possible, but if it requires new library, those library will has to be restored, built, and published

Using Visual Studio Community

Above should have prepared you well on different gears that make up the exciting ASP.NET 5. All of these steps can not only be simplified using Visual Studio, but you get all of the benefits of using Visual Studio as mentioned previously. But one huge benefit is that you can step through the code to debug! To setup the environment, follow below:

• Select New -> Project -> ASP.NET Web Application -> ASP.NET 5 -> Empty
• Make sure to change Solution Configuration to “Debug” instead of “Release”. Otherwise, it won’t step through the lines.
• Select “Run IIS Express” to see “Hello World” come up

Deploy to Local IIS from Visual Studio

That’s all good and it even let you step through your code thanks to tight integration with IIS Express. But what if you need to deploy the code to real IIS environment after the project completes? Here are the steps to publish your project to IIS using file”

• Create website on IIS with App Pool having .NET 4.0 selected
• Select Build -> Publish
• Select Profile Target -> File
• Enter profile name : “WebApplication1”
• Select Connection -> Select the website folder
• Select Settings -> Make sure to select Target DNX Version: “dnx-clr-win-x64.1.0.0-beta4” (64-bit) since your local IIS is probably a 64-bit version
• Select Settings -> File Publish Options -> Check “Delete all existing files prior to publish” so that it cleans the target directory. But sometimes there may be file lock issue. In that case, you may need to manually clean the target folder and uncheck this option.
• Select Settings -> Uncheck Publish using PowerShell script
• Finally, click Publish
• Then, load the website: http://localhost. Make sure that IIS service running and the website is mapped properly

Deploy to Subfolder of IIS

What if this new ASP.NET 5 MVC 6 app is part of a website, and that you cannot afford to setup a whole new website but this has to live as part of a subfolder within a website? Rest assured, here is how:

• Create a new App Pool account and assign .NET v4
• Create subfolder within the website
• Launch IIS Manager
• Right-click on the subfolder and choose “Convert to Application”
• Select the App Pool that we created
• From Visual Studio Community, publish to this folder
• In IIS, right click on this application -> Manage Application -> Advanced Setting
• Change “Physical Path” by adding “/wwwroot” at the end so that IIS is now running this web app on the wwwroot subfolder, yet web traffic cannot get to the web app folder which is essential for ASP.NET 5 web app to access approot where it loads all necessary code.

Congratulations! You have now successfully created a robust working environment to get start on your awesome ASP.NET 5 project. On the next article, I will cover what it took to create my first working version of project that satisfies all of my project requirement.

In the next post, Ready-Made ASP.NET 5 MVC 6 Web API Template – Grab It Now!, I will cover all of the lessons that I learned while trying to code a real world ASP.NET 5 MVC 6 application. Be sure to check it out!