AspNetCore.Docs/aspnetcore/migration/1x-to-2x/index.md

title	author	description	keywords	ms.author	manager	ms.date	ms.topic	ms.technology	ms.prod	uid
Migrating from ASP.NET Core 1.x to 2.0	scottaddie	This article outlines the prerequisites and most common steps for migrating an ASP.NET Core 1.x project to ASP.NET Core 2.0.	ASP.NET Core,migrating	scaddie	wpickett	08/01/2017	article	aspnet	asp.net-core	migration/1x-to-2x/index

Migrating from ASP.NET Core 1.x to ASP.NET Core 2.0

By Scott Addie

In this article, we'll walk you through updating an existing ASP.NET Core 1.x project to ASP.NET Core 2.0. Migrating your application to ASP.NET Core 2.0 enables you to take advantage of many new features and performance improvements.

Existing ASP.NET Core 1.x applications are based off of version-specific project templates. As the ASP.NET Core framework evolves, so do the project templates and the starter code contained within them. In addition to updating the ASP.NET Core framework, you need to update the code for your application.

Prerequisites

Please see Getting Started with ASP.NET Core.

Update Target Framework Moniker (TFM)

Projects targeting .NET Core should use the TFM of a version greater than or equal to .NET Core 2.0. Search for the <TargetFramework> node in the .csproj file, and replace its inner text with netcoreapp2.0:

[!code-xmlMain]

Projects targeting .NET Framework should use the TFM of a version greater than or equal to .NET Framework 4.6.1. Search for the <TargetFramework> node in the .csproj file, and replace its inner text with net461:

[!code-xmlMain]

[!NOTE] .NET Core 2.0 offers a much larger surface area than .NET Core 1.x. If you're targeting .NET Framework solely because of missing APIs in .NET Core 1.x, targeting .NET Core 2.0 is likely to work.

Update .NET Core SDK version in global.json

If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version property to use the 2.0 version installed on your machine:

[!code-jsonMain]

Update package references

The .csproj file in a 1.x project lists each NuGet package used by the project.

In an ASP.NET Core 2.0 project targeting .NET Core 2.0, a single metapackage reference in the .csproj file replaces the collection of packages:

[!code-xmlMain]

All the features of ASP.NET Core 2.0 and Entity Framework Core 2.0 are included in the metapackage.

ASP.NET Core 2.0 projects targeting .NET Framework should continue to reference individual NuGet packages. Update the Version attribute of each <PackageReference /> node to 2.0.0.

For example, here's the list of <PackageReference /> nodes used in a typical ASP.NET Core 2.0 project targeting .NET Framework:

[!code-xmlMain]

Update .NET Core CLI tools

In the .csproj file, update the Version attribute of each <DotNetCliToolReference /> node to 2.0.0.

For example, here's the list of CLI tools used in a typical ASP.NET Core 2.0 project targeting .NET Core 2.0:

[!code-xmlMain]

Rename Package Target Fallback property

The .csproj file of a 1.x project used a PackageTargetFallback node and variable:

[!code-xmlMain]

Rename both the node and variable to AssetTargetFallback:

[!code-xmlMain]

Update Main method in Program.cs

In 1.x projects, the Main method of Program.cs looked like this:

[!code-csharpMain]

In 2.0 projects, the Main method of Program.cs has been simplified:

[!code-csharpMain]

The adoption of this new 2.0 pattern is highly recommended and is required for product features like Entity Framework Core Migrations to work. For example, running Update-Database from the Package Manager Console window or dotnet ef database update from the command line (on projects converted to ASP.NET Core 2.0) generates the following error:

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Review your Razor View Compilation setting

Faster application startup time and smaller published bundles are of utmost importance to you. For these reasons, Razor view compilation is enabled by default in ASP.NET Core 2.0.

Setting the MvcRazorCompileOnPublish property to true is no longer required. Unless you're disabling view compilation, the property may be removed from the .csproj file.

When targeting .NET Framework, you still need to explicitly reference the Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet package in your .csproj file:

[!code-xmlMain]

Rely on Application Insights "Light-Up" features

Effortless setup of application performance instrumentation is important. You can now rely on the new Application Insights "light-up" features available in the Visual Studio 2017 tooling.

ASP.NET Core 1.1 projects created in Visual Studio 2017 added Application Insights by default. If you're not using the Application Insights SDK directly, outside of Program.cs and Startup.cs, follow these steps:

1. Remove the following <PackageReference /> node from the .csproj file:

   [!code-xmlMain]

2. Remove the UseApplicationInsights extension method invocation from Program.cs:

   [!code-csharpMain]

3. Remove the Application Insights client-side API call from _Layout.cshtml. It comprises the following two lines of code:

   [!code-cshtmlMain]

If you are using the Application Insights SDK directly, continue to do so. The 2.0 metapackage includes the latest version of Application Insights, so a package downgrade error appears if you're referencing an older version.

Adopt Authentication / Identity Improvements

ASP.NET Core 2.0 has a new authentication model and a number of significant changes to ASP.NET Core Identity. If you created your project with Individual User Accounts enabled, or if you have manually added authentication or Identity, see Migrating Authentication and Identity to ASP.NET Core 2.0.

Additional Resources

• Breaking Changes in ASP.NET Core 2.0