Migrate from ASP.NET Core 2.2 to 3.0 Preview 2

By Scott Addie and Rick Anderson

This article explains how to update an existing ASP.NET Core 2.2 project to ASP.NET Core 3.0 preview 2.

Prerequisites

Update the project file

  • Set the Target Framework Moniker (TFM) to netcoreapp3.0:

    <TargetFramework>netcoreapp3.0</TargetFramework>
    
  • Remove any <PackageReference> to the Microsoft.AspNetCore.All or Microsoft.AspNetCore.App metapackage.

  • Update the Version on remaining <PackageReference> elements for Microsoft.AspNetCore.* packages to the current preview (for example, 3.0.0-preview-18579-0053).

    If there is no 3.0 version of a package, the package might have been deprecated in 3.0. Many of these are part of Microsoft.AspNetCore.App and should not be referenced individually anymore. For a preliminary list of packages no longer produced in 3.0, see aspnet/AspNetCore #3756.

  • Some assemblies were removed from Microsoft.AspNetCore.App between 2.x and 3.0. You may need to add <PackageReference> items if you're using APIs from packages listed in aspnet/AspNetCore #3755.

    For example, Microsoft.EntityFrameworkCore and System.Data.SqlClient are no longer part of Microsoft.AspNetCore.App. The list of assemblies shipping in Microsoft.AspNetCore.App hasn't been finalized yet and will change before 3.0 RTM.

  • Add Json.NET support.

  • Projects default to the in-process hosting model in ASP.NET Core 3.0 or later. You may optionally remove the <AspNetCoreHostingModel> element if its value is InProcess.

Json.NET support

As part of the work to improve the ASP.NET Core shared framework, Json.NET has been removed from the ASP.NET Core shared framework.

To use Json.NET in an ASP.NET Core 3.0 project:

Newtonsoft settings can be set with AddNewtonsoftJson:

services.AddMvc()
    .AddNewtonsoftJson(options =>
           options.SerializerSettings.ContractResolver =
              new CamelCasePropertyNamesContractResolver());

HostBuilder replaces WebHostBuilder

The ASP.NET Core 3.0 templates use Generic Host. Previous versions used Web Host. The following code shows the ASP.NET Core 3.0 template generated Program class:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

The following code shows the ASP.NET Core 2.2 template-generated Program class:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

IWebHostBuilder remains in 3.0 and is the type of the webBuilder seen in the preceding code sample. WebHostBuilder will be deprecated in a future release and replaced by HostBuilder.

The most significant change from WebHostBuilder to HostBuilder is in dependency injection (DI). When using HostBuilder, you can only inject IConfiguration and IHostingEnvironment into Startup's constructor. The HostBuilder DI constraints:

  • Enable the DI container to be built only one time.
  • Avoids the resulting object lifetime issues like resolving multiple instances of singletons.

Update SignalR code

If you call AddJsonProtocol, replace it with AddNewtonsoftJsonProtocol.

  • The following examples show server code before and after the change:

    services.AddSignalR(...)
            .AddJsonProtocol(...) // 2.2
    
    services.AddSignalR(...)
            .AddNewtonsoftJsonProtocol(...) // 3.0
    
  • The following examples show .NET client code before and after the change:

    connection = new HubConnectionBuilder()
        .WithUrl(...)
        .AddJsonProtocol(...) // 2.2
        .Build()
    
    connection = new HubConnectionBuilder()
        .WithUrl(...)
        .AddNewtonsoftJsonProtocol(...) // 3.0
        .Build()
    

Opt in to runtime compilation

In 3.0, runtime compilation is an opt-in scenario. To enable runtime compilation, see Razor file compilation in ASP.NET Core.