升級 ASP.NET Core 2.0 專案到 2.1 的小記錄

利用修改 ASP.NET Core 2.0
專案的機會，來實作並記錄從 2.0 完整升級到 2.1 的作法。

基於以下幾個原因，建議將專案升級到 .NET Core 2.1，做為正式環境的標準：

長期支持（LTS）。
更好的性能和品質。
新的平台支持，例如：Ubuntu 18.04，Alpine，ARM32。
更容易在專案文件中管理平台依賴關係和自包含應用程序發佈。

背景資訊

進行操作前，記得先完成簽入或備份。
這個專案很簡單，沒有使用 Identity 功能。

專案的執行環境

Visual Studio 2017 15.8.7
.NET Core 2.0 SDK - Microsoft.AspNetCore.All(2.0.5)

調整專案檔 .csproj

將目標 framework 變更為 .NET Core 2.1
- <TargetFramework>netcoreapp2.1</TargetFramework>。
取代套件參考由 Microsoft.AspNetCore.All 改為 Microsoft.AspNetCore.App
- <PackageReference Include="Microsoft.AspNetCore.App" />。
- 移除 Version(版本) 屬性，平台會自動找到匹配的版本。
移除下列的工具參考(DotNetCliToolReference)，這些工具已預設在 .NET Core CLI 中，並不需要另外安裝
- Microsoft.DotNet.Watcher.Tools (dotnet watch)
- Microsoft.EntityFrameworkCore.Tools.DotNet (dotnet ef)
- Microsoft.Extensions.Caching.SqlConfig.Tools (dotnet sql-cache)
- Microsoft.Extensions.SecretManager.Tools (dotnet user-secrets)
在安裝全域版本的工具後可移除 Microsoft.VisualStudio.Web.CodeGeneration.Tools 的工具參考(DotNetCliToolReference)
- 安裝命令 : dotnet tool install -g dotnet-aspnet-codegenerator
利用 NuGet 更新其它套件參考。如範例中的 Microsoft.Extensions.Logging.Log4Net.AspNetCore。

2.0 版本的 csproj 範例

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <AssemblyName>My.Demo</AssemblyName>
    <RootNamespace>My.Demo</RootNamespace>
    <AssemblyVersion>1.0.0.77</AssemblyVersion>
    <FileVersion>1.0.0.77</FileVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.5" />
    <PackageReference Include="Microsoft.Extensions.Logging.Log4Net.AspNetCore" Version="2.0.1" />
  </ItemGroup>

  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.2" />
  </ItemGroup>

</Project>

2.1 版本的 csproj 範例

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <AssemblyName>My.Demo</AssemblyName>
    <RootNamespace>My.Demo</RootNamespace>
    <AssemblyVersion>1.0.0.77</AssemblyVersion>
    <FileVersion>1.0.0.77</FileVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Extensions.Logging.Log4Net.AspNetCore" Version="2.2.5" />
  </ItemGroup>

</Project>

其實，只調整 TargetFramework 到 netcoreapp2.1，其它部份都不改動，專案也可正確執行。

將程式碼改為 ASP.NET Core 2.1 的寫法

一部份的差別是增加了 GDPR 及 Cookie Policy 的支援。

Program.cs

調整 Build WebHost 的 method 責任；新的 CreateWebHostBuilder() 只負責建立 Builder。

2.1 版本

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

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

Startup.cs

ConfigureServices()

增加 services.Configure\(options…) : Cookie Policy 選項。
services.AddMvc() 增加 SetCompatibilityVersion(CompatibilityVersion.Version_2_1)。

Configure()

移除 UseBrowserLink()。
增加 UseHsts()。
增加 UseHttpsRedirection()。
增加 UseCookiePolicy()。

2.1 版本

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace WebApp1
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });


            services.AddMvc()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();
            // If the app uses Session or TempData based on Session:
            // app.UseSession();

            app.UseMvc();
        }
    }
}

MVC 專案的 Razor 檔案們

_Layout.cshtml

加入 GDPR 支援 <partial name="_CookieConsentPartial" />。
jQuery 從 2.2.0 變成 3.3.1。

_ValidationScriptsPartial.cshtml

變更 jquery.validate/1.14.0 為 jquery.validate/1.17.0。

新增 GDPR 相關檔案

新增 Views/Home/Privacy.cshtml。
Home Controller 加入 Privacy action。

LaunchSettings.json

主要是加了 HTTPS　的使用。

2.1 版的 launchSettings.json 檔案

{
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:39191",
      "sslPort": 44390
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

iisSettings 指定了 sslPort。
WebApp 的 applicationUrl 加入了 https 的網址。

Identity

2.1 版提供改動較大的 ASP.NET Core 2.1 Identity，請參閱參考資料取得詳細說明。也可保留 2.0 的 Identity，使用不受影響。

以上，開工吧！

參考資料及圖片來源

Migrate from ASP.NET Core 2.0 to 2.1