從 ASP.NET Core 2.0 移轉到 2.1

作者:Rick Anderson

如需ASP.NET Core 2.1中新功能的概觀,請參閱 ASP.NET Core 2.1 的新功能。

本文:

  • 涵蓋將 ASP.NET Core 2.0 應用程式移轉至 2.1 的基本概念。
  • 提供 ASP.NET Core Web 應用程式範本變更的概觀。

取得 2.1 變更概觀的快速方法是:

  • 建立名為 WebApp1 ASP.NET Core 2.0 Web 應用程式。
  • 認可原始檔控制系統中的 WebApp1。
  • 刪除 WebApp1,並在相同位置建立名為 WebApp1 的 ASP.NET Core 2.1 Web 應用程式。
  • 檢閱 2.1 版的變更。

本文提供移轉至 ASP.NET Core 2.1 的概觀。 它不包含移轉至 2.1 版所需的所有變更完整清單。 某些專案可能需要更多步驟,視建立專案時選取的選項和對專案所做的修改而定。

更新要使用 2.1 版的專案檔

更新專案檔:

  • 將專案檔更新為 ,將目標 Framework 變更為 <TargetFramework>netcoreapp2.1</TargetFramework> .NET Core 2.1。
  • 將 的封裝參考 Microsoft.AspNetCore.All 取代為 的 Microsoft.AspNetCore.App 套件參考。 您可能需要新增已從 Microsoft.AspNetCore.All 中移除的相依性。 如需詳細資訊,請參閱適用于 ASP.NET Core 2.0 的 Microsoft.AspNetCore.All 中繼套件Microsoft.AspNetCore.App ASP.NET Core 的中繼套件
  • 移除 封裝參考 Microsoft.AspNetCore.App 上的 「Version」 屬性。 使用 <Project Sdk="Microsoft.NET.Sdk.Web"> 的專案不需要設定版本。 目標 Framework 會隱含版本,並選取以最符合 2.1 ASP.NET Core運作方式。 如需詳細資訊,請參閱以 共用架構為目標之專案的規則 一節。
  • 針對以 .NET Framework 為目標的應用程式,請將每個套件參考更新為 2.1。
  • 移除下列套件的 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 ,將此工具取代為全域安裝的版本。
  • 針對 2.1,Razor 「類別庫」是散發 Razor 檔案的建議解決方案。 如果您的應用程式使用內嵌檢視,或依賴檔案的 Razor 執行時間編譯,請將 新增 <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory><PropertyGroup> 專案檔中的 。

下列標記顯示範本產生的 2.0 專案檔:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.3" />
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.4" />
  </ItemGroup>
</Project>

下列標記顯示範本產生的 2.1 專案檔:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.1" PrivateAssets="All" />
  </ItemGroup>

</Project>

以共用架構為目標的專案規則

「共用的架構」是一組不在應用程式資料夾內的組件 (.dll 檔案)。 共用的架構必須安裝於要執行應用程式的機器上。 如需詳細資訊,請參閱共用的架構 \(英文\)。

ASP.NET Core 2.1 包含下列共用架構:

套件參考所指定的版本是 所需的最低 版本。 例如,參考這些套件 2.1.1 版的專案不會在只安裝 2.1.0 執行時間的電腦上執行。

以共用架構為目標之專案的已知問題:

  • .NET Core 2.1.300 SDK (首先包含在 Visual Studio 15.6 中) 將 隱含版本的 Microsoft.AspNetCore.App 設定為 2.1.0,這會導致與 Entity Framework Core 2.1.1 衝突。 建議的解決方案是將 .NET Core SDK 升級至 2.1.301 或更新版本。 如需詳細資訊,請參閱 與 Microsoft.AspNetCore.App 共用相依性的套件無法參考修補程式版本

  • 所有必須使用 Microsoft.AspNetCore.AllMicrosoft.AspNetCore.App 的專案在專案檔中加入封裝參考,即使專案檔中包含另一個專案的專案參考,還是使用 Microsoft.AspNetCore.AllMicrosoft.AspNetCore.App

    範例:

    • MyApp 具有 的 Microsoft.AspNetCore.App 套件參考。
    • MyApp.Tests 具有 的專案 MyApp.csproj 參考。

    將 的 Microsoft.AspNetCore.App 套件參考新增至 MyApp.Tests 。 如需詳細資訊,請參閱 整合測試很難設定,而且可能會在共用架構服務上中斷

更新至 2.1 Docker 映射

在 ASP.NET Core 2.1 中,Docker 映射會遷移至dotnet/dotnet-docker GitHub 存放庫。 下表顯示 Docker 映射和標記變更:

2.0 2.1
microsoft/aspnetcore:2.0 microsoft/dotnet:2.1-aspnetcore-runtime
microsoft/aspnetcore-build:2.0 microsoft/dotnet:2.1-sdk

FROM變更Dockerfile中的行,以使用上表 2.1 資料行中的新映射名稱和標籤。 如需詳細資訊,請參閱 從 aspnetcore docker 存放庫移轉至 dotnet

Main 的變更

下圖顯示對樣板產生的 Program.cs 檔案所做的變更。

old version differences

上圖顯示以紅色刪除的 2.0 版本。

下圖顯示 2.1 程式碼。 綠色中的程式碼已取代 2.0 版本:

new version differences

下列程式碼顯示 的 2.1 版 Program.cs

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

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

新的 Main 會將 的 BuildWebHost 呼叫取代為 CreateWebHostBuilderIWebHostBuilder 已新增以支援新的 整合測試基礎結構

啟動的變更

下列程式碼顯示 2.1 範本產生的程式碼變更。 所有變更都是新增的程式碼,但已移除: UseBrowserLink

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();
        }
    }
}

上述程式碼變更詳述于:

驗證碼的變更

ASP.NET Core 2.1 提供 ASP.NET Core Identity 作為Razor 類別庫 (RCL) 。

預設的 2.1 Identity UI 目前未提供 2.0 版的重大新功能。 將 Identity 取代為 RCL 套件是選擇性的。 將範本產生的 Identity 程式碼取代為 RCL 版本的優點包括:

  • 許多檔案都會移出您的來源樹狀結構。
  • 要包含在Microsoft.AspNetCore.App 中繼套件中的任何錯誤修正或新功能 Identity 。 更新時 Microsoft.AspNetCore.App ,您會自動取得更新 Identity 。

如果您已對範本產生的 Identity 程式碼進行非簡單的變更:

  • 上述優點可能 合理地轉換為 RCL 版本。
  • 您可以保留 ASP.NET Core 2.0 Identity 程式碼,它完全受到支援。

Identity 2.1 會公開 Identity 具有區域的端點。 例如,下表顯示從 2.0 變更為 2.1 的 Identity 端點範例:

2.0 URL 2.1 URL
/Account/Login / Identity /Account/Login
/Account/Logout / Identity /Account/Logout
/Account/Manage / Identity /Account/Manage

使用 程式碼 Identity 並使用 2.0 程式庫取代 2.0 IdentityIdentity UI 的應用程式,必須考慮 Identity URL /Identity 前面加上區段。 處理新 Identity 端點的其中一種方式是設定重新導向,例如從 /Account/Login/Identity/Account/Login

更新 Identity 至 2.1 版

下列選項可用來更新 Identity 至 2.1。

  • 使用沒有變更的 Identity UI 2.0 程式碼。 完全支援使用 Identity UI 2.0 程式碼。 對產生的 Identity 程式碼進行重大變更時,這是很好的方法。
  • 刪除您現有的 Identity 2.0 程式碼,並將Scaffold Identity刪除至您的專案。 您的專案將會使用 ASP.NET Core IdentityRazor 類別庫。 您可以為任何修改過的 Identity UI 程式碼產生程式碼和 UI。 將您的程式碼變更套用至新 Scaffold 的 UI 程式碼。
  • 使用 [覆寫所有檔案] 選項,將現有的 Identity 2.0 程式碼和Scaffold Identity刪除至您的專案。

以 2.1 Razor 類別庫取代 Identity 2.0 UI Identity

本節概述以類別庫取代 ASP.NET Core 2.0 範本產生的 Identity 程式碼RazorASP.NET Core Identity 的步驟。 下列步驟適用于 Razor Pages 專案,但 MVC 專案的方法類似。

  • 確認 專案檔已更新為使用 2.1 版本
  • 刪除下列資料夾及其中的所有檔案:
    • 控制器
    • Pages/Account/
    • 擴充功能
  • 建置專案。
  • 支架 Identity進入您的專案:
    • 選取結束 _Layout.cshtml 檔案的專案。
    • +選取資料內容類別別右側的圖示。 接受預設名稱。
    • 選取 [新增 ] 以建立新的 [資料] 內容類別別。 必須建立新的資料內容,才能建立 Scaffold。 您會在下一節中移除新的資料內容。

Scaffolding 之後更新 Identity

  • Identity刪除Areas/ Identity /Data/資料夾中產生的 IdentityDbContext Scaffolder 衍生類別。

  • 刪除 Areas/Identity/IdentityHostingStartup.cs

  • 更新 _LoginPartial.cshtml 檔案:

    • Pages/_LoginPartial.cshtml 移至 Pages/Shared/_LoginPartial.cshtml
    • 新增 asp-area="Identity" 至表單和錨點連結。
    • <form /> 專案更新為 <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">

    下列程式碼顯示更新 的 _LoginPartial.cshtml 檔案:

    @using Microsoft.AspNetCore.Identity
    
    @inject SignInManager<ApplicationUser> SignInManager
    @inject UserManager<ApplicationUser> UserManager
    
    @if (SignInManager.IsSignedIn(User))
    {
        <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">
            <ul class="nav navbar-nav navbar-right">
                <li>
                    <a asp-area="Identity" asp-page="/Account/Manage/Index" title="Manage">Hello @UserManager.GetUserName(User)!</a>
                </li>
                <li>
                    <button type="submit" class="btn btn-link navbar-btn navbar-link">Log out</button>
                </li>
            </ul>
        </form>
    }
    else
    {
        <ul class="nav navbar-nav navbar-right">
            <li><a asp-area="Identity" asp-page="/Account/Register">Register</a></li>
            <li><a asp-area="Identity" asp-page="/Account/Login">Log in</a></li>
        </ul>
    }
    

使用下列程式碼更新 ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));

    services.AddDefaultIdentity<ApplicationUser>()
        .AddEntityFrameworkStores<ApplicationDbContext>()
        .AddDefaultTokenProviders();

    services.AddMvc();

    // Register no-op EmailSender used by account confirmation and password reset 
    // during development
    services.AddSingleton<IEmailSender, EmailSender>();
}

Pages 專案 Razor 檔的 Razor 變更

版面配置檔案

  • Pages/_Layout.cshtml 移至 Pages/Shared/_Layout.cshtml

  • Areas/ Identity /Pages/_ViewStart.cshtml中,將 變更 Layout = "/Pages/_Layout.cshtml"Layout = "/Pages/Shared/_Layout.cshtml"

  • _Layout.cshtml檔案有下列變更:

    • <partial name="_CookieConsentPartial" /> 已新增。 如需詳細資訊,請參閱 ASP.NET Core 的 GDPR 支援
    • jQuery 從 2.2.0 變更為 3.3.1。

_ValidationScriptsPartial.cshtml

  • Pages/_ValidationScriptsPartial.cshtml 會移至 Pages/Shared/_ValidationScriptsPartial.cshtml
  • jquery.validate/1.14.0jquery.validate/1.17.0所做的變更。

新增檔案

已新增下列檔案:

  • Privacy.cshtml
  • Privacy.cshtml.cs

如需上述檔案的相關資訊,請參閱 ASP.NET Core 中的 GDPR 支援

MVC 專案 Razor 檔案的變更

版面配置檔案

檔案 Layout.cshtml 有下列變更:

  • <partial name="_CookieConsentPartial" /> 已新增。
  • jQuery 從 2.2.0 變更為 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0jquery.validate/1.17.0所做的變更

新的檔案和動作方法

已新增下列專案:

  • Views/Home/Privacy.cshtml
  • Privacy動作方法會新增至 Home 控制器。

如需上述檔案的相關資訊,請參閱 ASP.NET Core 中的 GDPR 支援

launchSettings.json 檔案的變更

隨著 ASP.NET Core應用程式預設會使用 HTTPS,檔案 Properties/launchSettings.json 已變更。

下列 JSON 顯示先前的 2.0 範本產生的 launchSettings.json 檔案:

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:1799/",
      "sslPort": 0
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "WebApp1": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:1798/"
    }
  }
}

下列 JSON 顯示新的 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"
      }
    }
  }
}

如需詳細資訊,請參閱在 ASP.NET Core 中強制執行 HTTPS

重大變更

FileResult Range 標頭

FileResult 預設不會再處理 Accept-Ranges 標頭。 若要啟用 Accept-Ranges 標頭,請將 設定 EnableRangeProcessingtrue

ControllerBase.File 和 PhysicalFile Range 標頭

下列 ControllerBase 方法預設不會再處理 Accept-Ranges 標頭:

若要啟用 Accept-Ranges 標頭,請將 EnableRangeProcessing 參數設定為 true

ASP.NET CORE模組 (ANCM)

如果安裝 ASP.NET Core Visual Studio或系統上已安裝舊版 ANCM 時, (ANCM) (模組 (未選取元件,請下載最新的.NET Core 裝載套件組合安裝程式, (直接下載) 並執行安裝程式。 如需詳細資訊,請參閱 裝載套件組合

其他變更