Rion.IO

Making the Leap to ASP.NET MVC 6 Beta 8

Rion Williams -

I've been extremely happy with the new MVC6 environment (colloquially known as vNext) thus far. It's met all of my expectations and exceeded quite a few of them as well. Although one of the biggest challenges when developing in a Beta environment is that things break often, change often and generally require you to keep an eye on things.

The recent beta8 release is no exception. So I thought I would take a few minutes and summarize a few of the pitfalls and things that you'll need to do to get things running.

Get the Latest Beta 8 Environment

There are quite a few ways to do this - but if you are using Visual Studio as your primary development environment, then you can easily download the following installers to add in all of the necessary tooling to target this latest release :

After installing and restarting Visual Studio, you should have everything that you need to continue.

The Versions They Are A Changin'

The simplest change is going to be simply updating your current dependencies to target the -beta8 versions of themselves. You can do this by simply opening up your project.json file and updating the versions as expected (i.e. from -betaX to -beta8 as seen below :

"dependencies": {
    "EntityFramework.SqlServer": "7.0.0-beta8",
    "EntityFramework.Commands": "7.0.0-beta8",
    "Microsoft.AspNet.Mvc": "6.0.0-beta8",
    "Microsoft.AspNet.Mvc.TagHelpers": "6.0.0-beta8",
    "Microsoft.AspNet.Diagnostics": "1.0.0-beta8",
    "Microsoft.AspNet.Diagnostics.Entity": "7.0.0-beta8",
    "Microsoft.AspNet.Identity.EntityFramework": "3.0.0-beta8",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta8",
    "Microsoft.AspNet.Tooling.Razor": "1.0.0-beta8",
    "Microsoft.Framework.Configuration.Json": "1.0.0-beta8",
    "Microsoft.Framework.Configuration.UserSecrets": "1.0.0-beta8",
    "Microsoft.Framework.Logging": "1.0.0-beta8",
    "Microsoft.Framework.Logging.Console": "1.0.0-beta8",
    "Microsoft.VisualStudio.Web.BrowserLink.Loader": "14.0.0-beta8",
    "Microsoft.AspNet.Server.Kestrel": "1.0.0-beta8",
    "Microsoft.AspNet.IISPlatformHandler": "1.0.0-beta8",
    "EntityFramework.Core": "7.0.0-beta8",
    "Microsoft.Dnx.Runtime": "1.0.0-beta8",
    "Microsoft.ApplicationInsights.AspNet": "1.0.0-beta8"
},

All of these dependencies will likely not be necessary for your needs, but this is an example of a project that I was working on.

Moving to Kestrel and Dependency Changes

You might notice a few other changes within the previously shown project.json file. This is because this latest releases features several changes to the hosting model, specifically for IIS.

You'll need to perform the following changes within your project.json file :

  • Replace the dependency for Microsoft.AspNet.Server.IIS with Microsoft.AspNet.IISPlatformHandler.
  • Replace the dependency for Microsoft.AspNet.Server.WebListener with Microsoft.AspNet.Server.Kestrel
  • Update the web command in the commands section to target Kestrel via "commands": { "web": "Microsoft.AspNet.Server.Kestrel" ... }

So after those changes, your project.json file should look something like this :

"dependencies": {
    "EntityFramework.SqlServer": "7.0.0-beta8",
    "EntityFramework.Commands": "7.0.0-beta8",
    "Microsoft.AspNet.Mvc": "6.0.0-beta8",
    "Microsoft.AspNet.Mvc.TagHelpers": "6.0.0-beta8",
    "Microsoft.AspNet.Diagnostics": "1.0.0-beta8",
    "Microsoft.AspNet.Diagnostics.Entity": "7.0.0-beta8",
    "Microsoft.AspNet.Identity.EntityFramework": "3.0.0-beta8",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta8",
    "Microsoft.AspNet.Tooling.Razor": "1.0.0-beta8",
    "Microsoft.Framework.Configuration.Json": "1.0.0-beta8",
    "Microsoft.Framework.Configuration.UserSecrets": "1.0.0-beta8",
    "Microsoft.Framework.Logging": "1.0.0-beta8",
    "Microsoft.Framework.Logging.Console": "1.0.0-beta8",
    "Microsoft.VisualStudio.Web.BrowserLink.Loader": "14.0.0-beta8",
    "Microsoft.AspNet.Server.Kestrel": "1.0.0-beta8",
    "Microsoft.AspNet.IISPlatformHandler": "1.0.0-beta8",
    "EntityFramework.Core": "7.0.0-beta8",
    "Microsoft.Dnx.Runtime": "1.0.0-beta8",
    "Microsoft.ApplicationInsights.AspNet": "1.0.0-beta8"
},
"commands": {
    "web": "Microsoft.AspNet.Server.Kestrel",
    "ef": "EntityFramework.Commands"
},

And that should be it for the dependencies and any changes to your project.json file. Next up, we will look at some of the code-based changes that you'll need to make.

Changes to Starting Up

There are a few minor changes that you'll need to make within your Startup.cs file as well.

Previously, you could define the base path for your application via a constructor as seen below :

var builder = new ConfigurationBuilder(appEnv.ApplicationBasePath).Etc();

This is no longer the case in as the constructor approach has been changed in favor of the SetBasePath() method :

// Setting the base path for your application
var builder = new ConfigurationBuilder()
                  .SetBasePath(appEnv.ApplicationBasePath)
                  .Etc();

Error handling within the application has changed as well. Previously, you might use the following snippets to refer to error pages and actually handle errors :

if (env.IsDevelopment())
{
     // Omitted for brevity
     app.UseErrorPage();
}
else
{
     // Omitted for brevity
     app.UseErrorHandler("/YourController/YourErrorAction");
}

In this release, UseErrorPage() has been replaced with UseDeveloperExceptionPage() and UseErrorHandler() has been replaced with UseExceptionHandler() :

if (env.IsDevelopment())
{
     // Omitted for brevity
     app.UseDeveloperExceptionPage();
}
else
{
     // Omitted for brevity
     app.UseExceptionHandler("/YourController/YourErrorAction");
}

The final change is related to the previously mentioned Kestrel changes. If you are going to be using IIS to serve your application, you'll need to add the following line in your Configure() method :

// Indicates that IIS will be used
app.UseIISPlatformHandler();

Finally, the last major change involves services and how they are referenced. If you use a third-party site to handle your authentication such as Twitter or Facebook, you might find that you need to change how these services are wired up.

A previous call might look like :

services.Configure<TwitterAuthenticationOptions>(options =>
{
  options.AppId = Configuration["Authentication:Twitter:AppId"]; 
  options.AppSecret = Configuration["Authentication:Twitter:AppSecret"];
});

will change slightly and will use a more specific method call like :

// Using Twitter for authentication
app.UseFacebookAuthentication(options =>
{
  options.AppId = Configuration["Authentication:Twitter:AppId"]; 
  options.AppSecret = Configuration["Authentication:Twitter:AppSecret"];
});

And that's really it regarding the Startup.cs file.

Various Other Changes

There are a few other minor changes that are worth noting as well :

  • Uses of Context have been replaced with HttpContext within your Controllers.
  • The hosting.ini file at the root of your project has been deprecated.

Configuring Kestrel & Your web.config

After moving to Kestrel, you may need to update your web.config file found within the wwwroot directory to wire up the proper HTTP Handler as seen below :

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
    </handlers>
    <httpPlatform processPath="%DNX_PATH%" arguments="%DNX_ARGS%" forwardWindowsAuthToken="false" startupTimeLimit="3600" />
  </system.webServer>
</configuration>

NOTE: Ensure that you do not have any other elements present within the <handlers> section. I encountered several issues until I removed all of the ones besides httpPlatformHandler.
Your mileage may vary.

That's it (for now)

Hopefully this helped a few of you out there that are running along the bleeding-edge and following how the latest version of ASP.NET is progressing. If you need some additional resources or want to know more about everything that has changed in this latest release, you can read through some of the links below :