• Article

Special connect() issue 2014

Volume 29 Number 12A

ASP.NET 5 : Introducing the ASP.NET 5 Preview

Daniel Roth; issue 2014

ASP.NET shipped as part of the Microsoft .NET Framework 1.0, released in 2002 along with Visual Studio 2002. It was an evolution of Active Server Pages (ASP) that brought object-oriented design, the .NET Base Class Libraries (BCLs), better performance and much more. ASP.NET was designed to make it easy for developers used to writing desktop applications to build Web applications with ASP.NET Web Forms. As the Web evolved, new frameworks were added to ASP.NET: MVC in 2008, Web Pages in 2010, and Web API and SignalR in 2012. Each of these new frameworks built on top of the base from ASP.NET 1.0.

With ASP.NET 5, ASP.NET is being reimagined just like ASP was reimagined to ASP.NET in 2002. This reimagining brings many new features:

  • Full side-by-side support: ASP.NET 5 applications can now be installed on a machine without affecting any other applications on the machine.
  • Cross-platform support: ASP.NET 5 runs and is supported on Windows, Mac and Linux.
  • Cloud-ready: Features such as diagnostics, session state, cache and configuration are designed to work locally and in the cloud.
  • Faster development: The build step is removed; just save source files and refresh the browser and compilation happens automatically.
  • MVC, Web Pages and Web API: These are all merged together, simplifying the number of concepts.
  • Flexible hosting: You can now host your entire ASP.NET 5 application on IIS or in your own process.

Getting Started with ASP.NET 5 Preview

In this article, I’ll give an overview of the new experiences the ASP.NET development team—of which I’m a part—has created for ASP.NET 5 and Visual Studio 2015 Preview. For general help with building and running ASP.NET 5 applications, visit asp.net/vNext, where you can find step-by-step guides and additional documentation. In addition, we also post updates regularly to blogs.msdn.com/b/webdev. To get started, download and install Visual Studio 2015 Preview.

Overview of the ASP.NET 5 Runtime

ASP.NET 5 has been rebuilt from the ground up to support building modern Web applications and services. It’s open source, cross-platform and works both on-premises and in the cloud. ASP.NET 5 is currently in Preview and under active development on GitHub (github.com/aspnet). I’ll provide an overview of what’s new in the ASP.NET 5 Preview along with pointers to where you can learn more.

Flexible, Cross-Platform Runtime At its foundation, ASP.NET 5 is based on a new flexible runtime host. It provides the flexibility to run your application on one of three different runtimes:

  1. Microsoft .NET Framework: You can run your ASP.NET 5 applications on the existing .NET Framework. This gives you the greatest level of compatibility for existing binaries.
  2. .NET Core: A refactored version of the .NET Framework that ships as a set of NuGet packages that you can include with your app. With .NET Core, you get support for true side-by-side versioning and the freedom to use the latest .NET features on your existing infrastructure. Note that not all APIs are available yet on .NET Core, and existing binaries generally need to be recompiled to run on .NET Core.
  3. Mono: The Mono CLR enables you to develop and run ASP.NET 5 apps on a Mac or Linux device. For more information, see the blog post, “Develop ASP.NET vNext Applications on a Mac,” at bit.ly/1AdChNZ.

Regardless of which CLR is used, ASP.NET 5 leverages a common infrastructure for hosting the CLR and provides various services to the application. This infrastructure is called the K Runtime Environment (KRE). While it’s somewhat of a mystery where the “K” in KRE comes from (a tribute to the Katana Project? K for Krazy Kool?), the KRE provides everything you need to host and run your app.

A New HTTP Pipeline ASP.NET 5 introduces a new modular HTTP request pipeline that can be hosted on the server of your choice. You can host your ASP.NET 5 applications on IIS, on any Open Web Interface for .NET (OWIN)-based server or in your own process. Because you get to pick exactly what middleware runs in the pipeline for your app, you can run with as little or as much functionality as you need and take advantage of bare-metal performance. ASP.NET 5 includes middleware for security, request routing, diagnostics and custom middleware of your own design. For example, here’s a simple middleware implementation for handling of the X-HTTP-Method-Override header:

app.Use((context, next) =>
{
  var value = context.Request.Headers["X-HTTP-Method-Override"];
  if (!string.IsNullOrEmpty(value))
  {
    context.Request.Method = value;
  }
  return next();
});

ASP.NET 5 uses an HTTP pipeline model similar in many ways to the OWIN-based model introduced with Project Katana, but with several notable improvements. Like Katana, ASP.NET 5 supports OWIN, but simplifies development by including a lightweight and easy-to-use HttpContext abstraction.

There’s a Package for That Package managers have changed the way developers think about installing, updating and managing dependencies. In ASP.NET 5, all your dependencies are represented as packages. NuGet packages are the unit of reference. ASP.NET 5 makes it easy to build, install and use packages from package feeds and also to work with community packages on the node package manager (NPM) and Bower. ASP.NET 5 introduces a simple JSON format (project.json) for managing NuGet package dependencies and for providing cross-platform build infrastructure. An example project.json file is shown in Figure 1 (a more detailed explanation of each of the supported properties can be found on GitHub at bit.ly/1AIOhK3).

Figure 1 An Example project.json File

{
  "webroot": "wwwroot",
  "version": "1.0.0-*",
  "exclude": [
    "wwwroot"
  ],
  "packExclude": [
    "**.kproj",
    "**.user",
    "**.vspscc"
  ],
  "dependencies": {
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta1",
    "Microsoft.AspNet.Diagnostics": "1.0.0-beta1"
  },
  "frameworks" : {
    "aspnet50" : { },
    "aspnetcore50" : { }
  }
}

The Best of C# Design-time and run-time compilation for ASP.NET 5 applications are handled using the managed .NET Compiler Platform (code-named “Roslyn”). This means you get to take advantage of the latest C# language features while leveraging in-memory compilation to avoid unnecessary disk I/O. ASP.NET 5 projects are based on a new project system that dynamically compiles your application on-the-fly as you’re coding so you can avoid the interruption of a specific build step. This gives you the power of .NET and C# with the agility and feel of an interpreted language.

Built-in Dependency Injection All ASP.NET 5 applications have access to a common dependency injection (DI) service that helps simplify composition and testing. All the ASP.NET frameworks built on ASP.NET 5 (MVC, Web API, SignalR and Identity) leverage this common DI service. While ASP.NET 5 comes with a minimalistic Inversion of Control (IoC) container to bootstrap the system, you can easily replace that built-in IoC container with your container of choice.

Familiar Web Frameworks ASP.NET 5 includes frameworks for building Web apps and services such as MVC, Web API, Web Pages (coming in a future release), SignalR and Identity. Each of these frameworks has been ported to work on the new HTTP request pipeline and has been built to support running on the .NET Framework, .NET Core or cross-platform.

Today, the existing implementations of MVC, Web API and Web Pages share many concepts and duplicate abstractions, but share very little in the way of actual implementation. As part of porting these frameworks to ASP.NET 5, Microsoft decided to take a fresh look at combining these frameworks into a single unified Web stack. ASP.NET MVC 6 takes the best of MVC, Web API and Web Pages and combines it into a single framework for building Web UI and Web APIs. This means from a single controller you can just as easily render a view as return formatted data based on content negotiation.

In addition to unification, ASP.NET MVC 6 introduces a host of new features:

  • Built-in DI support
  • Ability to create controllers from any class—no base class required
  • Action-based request dispatching
  • View Components—a simple replacement for child actions
  • Routing improvements, including simplified attribute routing
  • Async views with flush points
  • Ability to inject servers and helpers into views using @inject
  • ViewStart inheritance
  • Tag helpers

You can find more information and samples at github.com/aspnet/mvc.

Web Forms isn’t available on ASP.NET 5, but is still fully supported on the .NET Framework. There are a number of important new features coming to Web Forms in the upcoming version of the .NET Framework, including support for HTTP 2.0, async model binding and a Roslyn-based CodeDom provider. We’re also working on various features reminiscent of Web Forms in MVC 6, such as tag helpers and other Razor improvements.

Entity Framework

Data is a key part of many applications and Entity Framework (EF) is a popular data access choice for ASP.NET developers. While EF7 isn’t specific to ASP.NET, this new version of EF plays an integral role in ASP.NET 5.

EF7 Enables New Platforms EF is widely used in client and server applications that target the full .NET Framework. A key focus of EF7 is to enable EF to be used on the remaining platforms where .NET development is common. These include ASP.NET 5, Windows Store and Windows Phone applications, as well as .NET-based Mac and Linux applications.

For Windows Phone and Windows Store applications, the initial goal is to provide local data access using EF. SQLite is the most common database of choice on devices and will be the primary store for local data on devices with EF7. The full provider model will be available, though, so other data stores can be supported also.

EF7 Enables New Data Stores While parts of EF are clearly tied to relational data stores, much of the functionality that EF provides is also applicable to many non-relational data stores. Examples of such functionality include change tracking, LINQ and unit of work. EF7 will enable providers that target non-relational data stores, such as Microsoft Azure Table Storage.

We’re explicitly not trying to build an abstraction layer that hides the type of data store you’re targeting. The common patterns/components that apply to most data stores will be handled by the core framework. Things specific to particular types of data stores will be available as provider-specific extensions. For example, the concept of a model builder that allows you to configure your model will be part of the core framework. However, the ability to configure things such as cascade delete on a foreign key constraint will be included as extensions in the relational database provider.

EF7 Is Lightweight and Extensible EF7 will be a lightweight and extensible version that pulls forward some commonly used features. In addition, we’ll be able to include some commonly requested features that would’ve been difficult to implement in the EF6 code base, but which can be included from the start in EF7.

The team will be keeping the same patterns and concepts you’re used to in EF, except where there’s a compelling reason to change something. You’ll see the same DbContext/DbSet-based API, but it will be built over building block components that are easy to replace or extend as needed—the same pattern used for some of the isolated components added in recent EF releases.

More Information on EF7 For more information on EF7, visit the “What Is EF7 All About” GitHub page at aka.ms/AboutEF7. The page includes design information, links to blog posts and instructions for trying out EF7.

ASP.NET Command-Line Tools

One of the core ASP.NET 5 tenets was to provide a command-line experience before we built the tooling experience. This means that almost all tasks you need to do with an ASP.NET 5 application can be done from the command line. The main reason for this is to ensure a viable option for using ASP.NET 5 without Visual Studio for those using Mac or Linux machines.

KVM The first tool you need to get the full command-line experience for ASP.NET 5 is the K Version Manager (KVM). The KVM command-line tool can download new versions of the KRE and let you switch between them. KRE contains other command-line tools that you might use. How KVM is implemented, and how to get it, depends on the OS. You can download and install KVM for your platform by running the appropriate command from github.com/aspnet/Home.

Once you have KVM, you should be able to open a command prompt and run the kvm command. If you run “kvm list,” you’ll see the list of all KRE versions on your machine, as shown in Figure 2.

Running “kvm list” at the Command Line to Get a List of KRE Versions on Your Machine
Figure 2 Running “kvm list” at the Command Line to Get a List of KRE Versions on Your Machine

If there are no entries in your list, there are no versions of KRE in your user profile. To fix this, you can run the command “kvm upgrade.” This command will determine the latest version of the KRE available, download it and modify your PATH environment variable so you can use the other command-line tools in the KRE itself.

You can use “kvm install <version/latest>” to install a particular version without making it the default. Use the –r switch to indicate whether you want the .NET Core or .NET Framework version of the KRE and the –x86 and –amd64 switches to download the 32- or 64-bit flavors of the KRE. The runtime and bitness switches can be supplied to either install or upgrade.

Once you’ve called “kvm upgrade,” you’ll be able to use the K and KPM commands. K can be used to run applications, while KPM is used to manage packages.

How does KVM work? At its heart, KVM is just a convenient way to manipulate your PATH. When you use “KVM use <version>,” all it does is change your PATH to the bin folder of the KRE version you specified is on your PATH. By default the KRE is installed by copying and extracting the KRE .zip file into %USERPROFILE%\.kre\packages, so when you type “KVM use 1.0.0-beta1,” KVM will make sure that %USERPROFILE%\.kre\packages\KRE-CLR-x86.1.0.0-beta1\bin is on your PATH.

KPM The next tool you’ll want to use is the KRE Package Manager (KPM). The KPM performs two main functions, with a few lesser features:

  1. You can run “kpm restore” in a folder with a project.json file to download all the packages your application needs.
  2. It provides the pack command, “kpm pack,” which will take your application and generate a self-contained, runnable image of your application. Here, image means a folder structure that’s designed to be copied to the server and run. It will include all the packages your application requires, as well as, optionally, the KRE on which you want to run the application.

The restore command can be run in a folder that contains a project.json file. It will examine the file and, using NuGet.config, connect to a NuGet feed and attempt to download all the packages your application needs. By default, it will install these packages in %USERPROFILE%\.kpm\packages so only one copy of any given package needs to be on your dev machine, even if used in multiple projects.

Packing your application—by running “kpm pack”—will generate a folder containing everything your app needs to run, including packages, source files and your Web root. You can even optionally include the KRE, although by default it’s assumed the KRE is already on the server.

K Command The K command actually runs an ASP.NET 5 application from the command line. The K command is included in the KRE, the same as KPM, and is the entry point to running an application on top of the KRE.

The main way to use the K command is to run one of the commands inside your project.json file. Commands are specified by name in the project.json file under the commands property. By default, the ASP.NET 5 Starter Web template includes a “web” command in project.json that hosts your app and listens on port 5000. To run this command, simply run “k web.”

Visual Studio Updates for ASP.NET 5

One of the original goals of ASP.NET 5 was to have a great experi­ence for teams in which members use different tools. For example, you can have team members using Windows and Visual Studio working with others who are using Sublime Text on a Mac (see options for cross-platform .NET development tools at omnisharp.net). To achieve this, we had to take a step back and rethink Visual Studio support. In previous versions of Visual Studio, the project system assumed that most development was performed in Visual Studio. Visual Studio didn’t work well when other tools were involved to create files or modify the project. For example, in the .csproj file, Visual Studio maintained a list of files that made up the project. If you used a tool to create a new file for your project, you’d then have to edit the .csproj file for it to be included.

In Visual Studio 2015, when you create a new ASP.NET 5 project, you get a new experience. You can still develop, debug and run your project as usual, but in addition to the standard features that you’ve come to know in ASP.NET projects, some new features are unique to ASP.NET 5. You now have the freedom to develop using the platform and tooling of your choice. I’ll discuss some of those features.

Support for All Files in the Folder In ASP.NET 5, all files under the project directory are automatically included in the project. You can exclude files from compile or publish in the project.json file. For more info on how to exclude files in project.json, see the GitHub page at bit.ly/1AIOhK3. After the project is loaded, Visual Studio starts a file watcher and updates Solution Explorer to reflect the changes. Because Solution Explorer is always watching the files under the project directory, we’ve changed the location where generated files will be stored. Instead of storing generated files under the project (bin\ and obj\), we now place generated files by default in a folder named artifacts next to the solution file.

Just Edit, Save and Refresh the Browser In existing ASP.NET applications, when you change server-side logic (such as your MVC controller code, or a filter) then you need to rebuild and redeploy the application to see the changes reflected in the browser. Microsoft wanted the Web developer workflow to feel as lightweight and agile as when working with interpreted platforms (such as Node.js or Ruby), while still letting you leverage the power of .NET. In ASP.NET 5 projects, when you edit and save your C# code, a file watcher detects the change and restarts the application. The application is rebuilt in memory, so you can see the results of the change in the browser in near-real time. Note that this workflow is only supported when you aren’t debugging so as to avoid interrupting your debugging session.

Updated Support for NuGet Packages In ASP.NET 5 all your dependencies are NuGet packages. Your package dependencies are listed in project.json and only direct references are listed. The runtime resolves package dependencies for you and you can see and search through the entire graph of your package dependencies in the Solution Explorer.

To install a NuGet package, you simply add the package to your project.json file. As soon as you save the project.json file, a package restore command is initiated and any changes to your dependencies are reflected in the References node in the Solution Explorer. You can see the result of the package restore and any errors that might have occurred in the package manager log in the Output window. You even get IntelliSense for packages installed locally on the machine with Visual Studio and packages that are available on the public NuGet feed, as shown in Figure 3.

IntelliSense for NuGet Package Dependencies in project.json
Figure 3 IntelliSense for NuGet Package Dependencies in project.json

In existing ASP.NET projects, when you install a NuGet package into a project, a copy of that NuGet package (and all of its dependencies) gets placed in a packages folder near the solution. In ASP.NET 5, a cache is used so NuGet packages are shared across projects for each user. When a package restore occurs in ASP.NET 5, any packages already installed in the cache are simply reused. You can see and modify the package cache in your user profile under the .kpm folder.

By default, ASP.NET 5 projects are built in-memory by the runtime and no artifacts are persisted to disk. However, you can easily enable building NuGet packages for your ASP.NET 5 class libraries by selecting the “Produce all outputs on build” checkbox on the Build tab of the Properties page for the project. Once this option is selected, you can find the built NuGet package under the artifacts folder for the solution.

Build and Get Combined IntelliSense for Multiple Target Frameworks In ASP.NET 5, you list your target frameworks in project.json. Your project is built against every target framework listed. This makes discovering issues much quicker because you don’t have to explicitly switch to that target framework and you can cross-compile for multiple target frameworks from a single project.

We’ve also updated the IntelliSense experience for ASP.NET 5 project with Combined IntelliSense. With Combined Intellisense, when the IntelliSense for a given completion differs for one or more of the target frameworks, you’ll see an expanded tooltip to show you the differences. You can see this in Figure 4 for the StringComparison class.

Tooltip Showing Combined IntelliSense for Multiple Target Frameworks
Figure 4 Tooltip Showing Combined IntelliSense for Multiple Target Frameworks

In Figure 4, you can see that the InvariantCulture value isn’t available for the StringComparison enum when using ASP.NET Core 5.0.

Web Publishing In Visual Studio 2015, Microsoft developers are working on a new publish process for ASP.NET 5 projects. In the Preview release, ASP.NET 5 publishing supports publishing to Azure Websites and to the file system (for example, local/network folder). When publishing to Azure Websites, you can select the desired build configuration and KRE version. Later releases will expand this to support a broader set of targets.

Migrating to ASP.NET 5

Moving existing Web applications to ASP.NET 5 involves both creating a new ASP.NET 5 project for your existing application and then migrating your code and dependencies to run on the new framework. Creating a new ASP.NET 5 project for your application is relatively simple. First, add a project.json file in your project folder. Initially, the project.json file only needs to include an empty JSON object (for example, {}). Next, use File | Open Project to open the project.json file in Visual Studio 2015 Preview. After opening the project.json file, Visual Studio will create an ASP.NET 5 project with a .kproj file and automatically include in the project all the files and directories it finds next to the project.json file. You should see your project files in your new ASP.NET 5 project in the Solution Explorer. You have now created an ASP.NET 5 project for your existing Web application!

Migrating your code and dependencies so your new ASP.NET 5 project builds and runs correctly is a more involved process. You need to update your project.json with your top-level package dependencies, framework assembly references and project references. You need to migrate your code to use the new HTTP abstractions, the new middleware model and the new versions of the ASP.NET Web frameworks. You need to move to new infrastructure for handling concerns such as configuration, logging and DI. Porting your application to run on .NET Core requires dealing with additional platform changes and limitations. This is more than can be covered in this article, but we’re working hard to provide complete migration guidance in a future article. While the investment to move to ASP.NET 5 might be significant, Microsoft believes the benefits of providing an open source, community-driven, cross-platform and cloud-ready framework are worth the additional effort.

Where to Go from Here?

In this article, I’ve explored ASP.NET 5 from high-level concepts to low-level components. There’s a lot to learn! Fortunately, there are plenty of resources to help.

The ASP.NET site has a dedicated content area at asp.net/vnext. This page is constantly updated to feature release news, documentation, tutorials and community resources.

The ASP.NET vNext Community Standup is an open weekly meeting with the ASP.NET team. It’s held every Tuesday, alternating between morning and afternoon Pacific Time, so developers around the world can attend. Come join us to hear what’s coming next, ask questions and give your feedback.

You can get help from fellow developers and ASP.NET team members in the dedicated ASP.NET vNext forum at bit.ly/1xOuQx9. There’s also a chat room in JabbR.net focused on ASP.NET 5/vNext development at bit.ly/1HDAGFX.

Because ASP.NET 5 is being developed as an open source project, you can get involved in the development process. The source repositories under github.com/aspnet are the actual, live repositories the team develops against, not a mirror of an internal repository. This means you can see the commits as they happen and grab a snapshot of the code at any time. The repositories include source code for the frameworks (for example, KRuntime, Razor and MVC), as well as functional tests and sample projects. We encourage you to leave feedback—both bugs and feature suggestions—by opening or commenting on issues in the GitHub repositories.

It’s an exciting time for Web development on the Microsoft Web platform! We encourage you to get involved early, both so you’ll be ready to take advantage of the new features and so you can provide feedback during the development process.

Finally, I want to thank Glenn Condron, Jon Galloway, Sayed Ibrahim Hashimi, Scott Hunter and Rowan Miller for going beyond the call of regular technical review duties and actually contributing significant parts of this article.

Daniel Roth is a senior program manager on the ASP.NET team currently working on ASP.NET 5. His passions include .NET development and delighting customers by making frameworks simple and easy-to-use.

Thanks to the following Microsoft technical experts for reviewing this article: Glenn Condron, David Fowler, Jon Galloway, Sayed Ibrahim Hashimi, Scott Hunter, Rowan Miller and Praburaj Thiagaraj