從 ASP.NET Core 2.0 移轉到 2.1
如需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.DotNet.Watcher.Tools (
- 選擇性:您可以移除 的
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.All
或Microsoft.AspNetCore.App
的專案在專案檔中加入封裝參考,即使專案檔中包含另一個專案的專案參考,還是使用Microsoft.AspNetCore.All
或Microsoft.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。
變更以利用 ASP.NET Core 2.1 中建議的新程式碼型慣用語
Main 的變更
下圖顯示對樣板產生的 Program.cs
檔案所做的變更。
上圖顯示以紅色刪除的 2.0 版本。
下圖顯示 2.1 程式碼。 綠色中的程式碼已取代 2.0 版本:
下列程式碼顯示 的 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
呼叫取代為 CreateWebHostBuilder 。 IWebHostBuilder 已新增以支援新的 整合測試基礎結構。
啟動的變更
下列程式碼顯示 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();
}
}
}
上述程式碼變更詳述于:
- 和
UseCookiePolicy
ASP.NET CoreCookiePolicyOptions
中的 GDPR 支援。 - 的
UseHsts
HTTP 嚴格傳輸安全性通訊協定 (HSTS) 。 - 需要 的
UseHttpsRedirection
HTTPS。 - 的
SetCompatibilityVersion(CompatibilityVersion.Version_2_1)
SetCompatibilityVersion。
驗證碼的變更
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.0 對 jquery.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.0對jquery.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
標頭,請將 設定 EnableRangeProcessing 為 true
。
ControllerBase.File 和 PhysicalFile Range 標頭
下列 ControllerBase 方法預設不會再處理 Accept-Ranges 標頭:
若要啟用 Accept-Ranges
標頭,請將 EnableRangeProcessing
參數設定為 true
。
ASP.NET CORE模組 (ANCM)
如果安裝 ASP.NET Core Visual Studio或系統上已安裝舊版 ANCM 時, (ANCM) (模組 (未選取元件,請下載最新的.NET Core 裝載套件組合安裝程式, (直接下載) 並執行安裝程式。 如需詳細資訊,請參閱 裝載套件組合。