Upgrading from ASPNET Core RC1 to RC2 Guide

Upgrading from ASPNET Core RC1 to RC2 Guide

There are a number of breaking changes between ASP.NET Core RC1 and RC2. If you have existing apps targeting RC1, here are some things you should expect to change in order to upgrade the apps to RC2. Consider this an “unofficial” guide.

Update: The official docs have a bunch of great content on this as well – this was just my own personal notes that worked for my projects.

NuGet Sources

Make sure you’re configured to use the correct NuGet feed(s) for the RC2 sources. Once RC2 officially ships, the official, standard NuGet source should work, but until then you may need to use manually specify the correct source using the nuget command line (nuget sources) or a NuGet.config file. As of now you should be using:

Update: The RC2 packages are all on nuget.org now, so you can use your usual nuget.org package source.

You can browse to that link to see the available packages and their respective versions. You can specify this source in  Nuget.Config file like this one (note the other two sources shown are commented out):

dotnet CLI

Make sure you have installed the latest dotnet command line interface (CLI), using the .NET Core SDK. You can find the dotnet CLI installer appropriate to your OS here.

project.json

The project.json file structure has changed in a number of subtle ways. You’ll of course need to change the versions of all of the packages you’re using, and change the references to any that use “Microsoft.AspNet” to be “Microsoft.AspNetCore” (see below for more of this). The current rc2 version that is working for me is “1.0.0-rc2-20801” but I expect this number will change to another string upon release (e.g. “1.0.0-rc2” or “1.0.0-rc2-final”).

Note: commands are gone.

Here is an example of a working project.json file (from the dependency injection docs):

Namespaces

Do a search for “Microsoft.AspNet.” in your project to find all of the namespaces that use this string, and replace them with “Microsoft.AspNetCore.” This will fix the bulk of the compile errors you will encounter immediately. Don’t forget to look in your views, including _ViewImports.cshtml, for additional references to namespaces that need updated that the compiler won’t catch (you’ll encounter these problems at runtime).

“Microsoft.Framework” has been renamed to “Microsoft.Extensions”. This affects packages and namespaces like DependencyInjection and Logging.

“Microsoft.AspNet.Identity.EntityFramework” is now “Microsoft.AspNetCore.Identity.EntityFrameworkCore”.

global.json

You can remove the “sdk” section. Typically it will just list the projects (e.g. “projects” : [“src”,”test”]).

Startup.cs

Remove references to UseIISPlatformHandler.

Remove the public static void main entry point. You’ll add a Program.cs file (see below).

Remove minimumLevel property from loggerFactory (it’s specified per logger type now), if set.

Change any reference to LogLevel.Verbose (to Information or Debug).

If building configuration, you can use AddJsonFile(“file.json”,optional: true, reloadOnChange: true) instead of calling .ReloadOnChanged() off of your call to builder.Build().

Access to the root of the application is now through IHostingEnvironment.ContentRootPath.

If configuring Entity Framework, change call in ConfigureServices from AddEntityFramework to AddDbContext.

If using services.Configure<T>(Configuration.GetSection(“sectionName”) you need to reference Microsoft.Extensions.Options.ConfigurationExtensions and add a  using Microsoft.Extensions.DependencyInjection; if you aren’t already doing so.

Below is an example Startup.cs:

Entity Framework

If you’re using Entity Framework, you’ll need to update your DbContext class to accept an options parameter in its constructor and pass it to its base, like so:

Call AddDbContext in Startup as mentioned above.

Change namespace from “Microsoft.Data.Entity” to “Microsoft.EntityFrameworkCore”.

Migrations will need to be updated. For instance, “.HasAnnotation(“Relational:Name”, “name”)” is now simply “.HasName(“name”)”. Likewise, HasAnnotation(“Relational:TableName”, tableName) should be updated to ToTable(tableName).

References to “Microsoft.AspNet.Identity.EntityFramework” will need to be changed to “Microsoft.AspNetCore.Identity.EntityFrameworkCore”.

Table names will now use the DbSet name, not the Type name, so you may run into issues especially around pluralization. See here for resolutions.

Program.cs

You should add a Program.cs file to configure your web app. Here’s an example:

Razor

Change validation summary tag helpers from asp-validation-summary=”ValidationSummary.All” to asp-validation-summary=”All”. Likewise change “ValidationSummary.ModelOnly” to “ModelOnly”.

Add to form tags asp-route-returnurl=”@ViewData[“ReturnUrl”]” if you wish to use this functionality (and be sure to set this in ViewData).

Don’t forget to change _ViewImports.cshtml. Its reference to TagHelpers should be
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

(and change the reference to Identity to use AspNetCore as well)

Properties – launchSettings.json

You need to change the environment variable name used to set the environment to Development in launchSettings.json. Here’s a sample of the file:

API Changes

There are many small API changes, as well. Please list those that you find in the comments and I will update this list. Here are the ones I’ve encountered myself thus far. You can find the team’s summary of changes listed in the issues in the Announcements repository on GitHub.

  • IFilterFactory: now has a boolean IsReusable property that must be implemented.
  • [FromServices]: this attribute is no longer available; use constructor injection instead (learn more)
  • IActionResult HttpNotFound: this has been renamed NotFound
  • IActionResult HttpBadRequest: this has been renamed BadRequest
  • ASPNET_ENV environment variable is now ASPNETCORE_ENVIRONMENT
  • Microsoft.Extensions.WebEncoders namespace is now System.Text.Encodings.Web (for HtmlEncoder)

Training

If you or your team need training on ASP.NET Core, I have a virtual 2-day ASP.NET Core class scheduled for June, and I’m available to schedule a custom class for your team, as well.

  • Chema

    Good job man, thanks!!