Migrate existing ASP.Net Core 2.0 application to ASP.Net Core 2.1

ASP.NET Core 2.1 preview 1 is already out and available for everyone. Read this post to find out how to get started with it. ASP.NET Core 2.1 comes with lots of new features like HTTPS by default, HTTPClientFactory, SignalR, and others. To know all the new features, you can read this post. So now it’s a good time to migrate existing ASP.NET Core 2.0 application to ASP.NET Core 2.1.

Migrate existing ASP.Net Core 2.0 application to ASP.Net Core 2.1

As there are no major code breaking changes in ASP.NET Core 2.1, the migration process is straightforward. Follow these steps to migrate an existing ASP.NET Core 2.0 application to 2.1 preview 1:

  • Update the target framework to .NET Core 2.1. This can be done in 2 ways. Right click on Project and then Properties -> Application tab -> Target framework -> select .Net Core 2.1 as below:

    Migrate existing .Net Core application to .Net Core 2.1

    Or
    You can edit the .csproj file and set target framework. Like,

    1
    2
    3
    <PropertyGroup>
       <TargetFramework>netcoreapp2.1</TargetFramework>
    </PropertyGroup>
  • Next, we need to update the package reference. Remember, ASP.NET Core 2.1 introduces a new meta-package for use by applications: Microsoft.AspNetCore.App. So the 2.1 projects must target to this meta-package, rather than the existing meta-package Microsoft.AspNetCore.All. Your existing .csproj may look like this,
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore" Version="2.0.1" />
      <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.1" />
    </ItemGroup>
     
    <ItemGroup>
      <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
    </ItemGroup>

    We need to update the versions of the packages for any Microsoft.AspNetCore, Microsoft.Extensions, and Microsoft.EntityFrameworkCore packages to 2.1.0. Also, update the versions of the various <DotNetCliToolReference> elements for any Microsoft.VisualStudio, and Microsoft.EntityFrameworkCore packages to 2.1.0.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.0" />
      <PackageReference Include="Microsoft.EntityFrameworkCore" Version="2.1.0" />
      <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.0" />
    </ItemGroup>
     
    <ItemGroup>
      <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.1.0" />
    </ItemGroup>

That’s it. Your ASP.NET Core 2.0 application is now ready to build and run against 2.1.0-preview1. Please note that your project might require some additional steps depending on the packages referenced.

 

Here, we are not utilizing any of the new features and code-based idioms recommended in ASP.NET Core 2.1. Let’s implement HTTPS by default and new code changes in Program.cs file.

  • In ASP.NET Core 2.1, BuildWebHost is changed to CreateWebHostBuilder. Here is your ASP.NET Core 2.0 Program.cs file code,
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }
     
        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }

    Below is the code of Program.cs in ASP.NET Core 2.1.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }
     
        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
           WebHost.CreateDefaultBuilder(args)
               .UseStartup<Startup>();
    }

    Update the Program.cs code to match with ASP.NET Core 2.1 code-based idioms. If you want to skip this, it’s fine as things still work.

  • To enable HTTPS, we need to add 2 middlewares to Configure method. So open Startup.cs class and navigate to Configure method. Add a call to add the HSTS middleware after the exception handler middleware: app.UseHsts(); and then add a call to add the HTTPS redirection middleware before the static files middleware: app.UseHttpsRedirection();. Like,
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }
     
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseCookiePolicy();
     
        app.UseAuthentication();
        app.UseMvc();
    }

    The HSTS protocol enforces clients (web browsers or other complying user agents) to interact with the server via HTTPS connections, and never via the HTTP protocol. HSTS protocol is typically used in non-development scenarios, therefore the UseHSTS() middleware is added in the else part of the code.

    Next, we need to enable SSL for the project. To do that, right click on the project and then Properties -> Debug tab -> check the “Enable SSL” checkbox and save the changes. Also, add an environment variable named ASPNETCORE_HTTPS_PORT and set its value to the port number displayed in the URL against the “Enable SSL” checkbox.

    Enable SSL for ASP.NET Core 2.1

    Lastly, Open the launchSettings.json file. This file is located under Properties. In the launchSettings.json, add a new property “sslPort” in the “iisSettings”/”iisExpress” section. The value will be the SSL port number set to the ASPNETCORE_HTTPS_PORT environment variable. Like,

    1
    2
    3
    4
    5
    6
    7
    8
    "iisSettings": {
       "windowsAuthentication": false,
       "anonymousAuthentication": true,
       "iisExpress": {
         "applicationUrl": "http://localhost:57905/",
         "sslPort": 44395
       }
    }

    That’s it. These configurations value will be read by the HTTPS redirect middleware to ensure non-HTTPS requests are redirected to the correct port.

Conclusion

To conclude, this post shows the steps to migrate existing ASP.NET Core 2.0 application to ASP.NET Core 2.1. It’s a very straightforward process as no major code breaking changes introduced in ASP.NET Core 2.1. The post also shows how you can enable HTTPS for the ASP.NET Core application.

Thank you for reading. Keep visiting this blog and share this in your network. Please put your thoughts and feedback in the comments section.

 
 
 

Add comment