Migrasi dari ASP.NET Core 2.0 ke 2.1

Artikel
11/30/2023

Lihat Apa yang baru di ASP.NET Core 2.1 untuk gambaran umum fitur baru di ASP.NET Core 2.1.

Artikel ini:

Mencakup dasar-dasar migrasi aplikasi ASP.NET Core 2.0 ke 2.1.
Memberikan gambaran umum tentang perubahan pada templat aplikasi web ASP.NET Core.

Cara cepat untuk mendapatkan gambaran umum perubahan di 2.1 adalah dengan:

Buat aplikasi web ASP.NET Core 2.0 bernama WebApp1.
Terapkan WebApp1 dalam sistem kontrol sumber.
Hapus WebApp1 dan buat aplikasi web ASP.NET Core 2.1 bernama WebApp1 di tempat yang sama.
Tinjau perubahan dalam versi 2.1.

Artikel ini memberikan gambaran umum tentang migrasi ke ASP.NET Core 2.1. Ini tidak berisi daftar lengkap semua perubahan yang diperlukan untuk bermigrasi ke versi 2.1. Beberapa proyek mungkin memerlukan lebih banyak langkah tergantung pada opsi yang dipilih saat proyek dibuat dan modifikasi yang dilakukan pada proyek.

Memperbarui file proyek untuk menggunakan versi 2.1

Perbarui file proyek:

Ubah kerangka kerja target menjadi .NET Core 2.1 dengan memperbarui file proyek menjadi <TargetFramework>netcoreapp2.1</TargetFramework>.
Ganti referensi paket untuk Microsoft.AspNetCore.All dengan referensi paket untuk Microsoft.AspNetCore.App. Anda mungkin perlu menambahkan dependensi yang dihapus dari Microsoft.AspNetCore.All. Untuk informasi selengkapnya, lihat Metapackage Microsoft.AspNetCore.All untuk metapackage ASP.NET Core 2.0 dan Microsoft.AspNetCore.App untuk ASP.NET Core.
Hapus atribut "Versi" pada referensi paket ke Microsoft.AspNetCore.App. Proyek yang menggunakan <Project Sdk="Microsoft.NET.Sdk.Web"> tidak perlu mengatur versi. Versi ini tersirat oleh kerangka kerja target dan dipilih agar paling sesuai dengan cara kerja ASP.NET Core 2.1. Untuk informasi selengkapnya, lihat bagian Aturan untuk proyek yang menargetkan kerangka kerja bersama.
Untuk aplikasi yang menargetkan .NET Framework, perbarui setiap referensi paket ke 2.1.
Hapus referensi ke <elemen DotNetCliToolReference> untuk paket berikut. Alat-alat ini dibundel secara default di .NET Core CLI dan tidak perlu diinstal secara terpisah.
- 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)
Opsional: Anda dapat menghapus elemen DotNetCliToolReference> untuk Microsoft.VisualStudio.Web.CodeGeneration.Tools.< Anda dapat mengganti alat ini dengan versi yang diinstal secara global dengan menjalankan dotnet tool install -g dotnet-aspnet-codegenerator.
Untuk 2.1, Razor Pustaka Kelas adalah solusi yang direkomendasikan untuk mendistribusikan Razor file. Jika aplikasi Anda menggunakan tampilan yang disematkan, atau bergantung pada kompilasi Razor runtime file, tambahkan <CopyRefAssembliesToPublishDirectory>true</CopyRefAssembliesToPublishDirectory> ke <PropertyGroup> dalam file proyek Anda.

Markup berikut menunjukkan file proyek 2.0 yang dihasilkan templat:

<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>

Markup berikut menunjukkan file proyek 2.1 yang dihasilkan templat:

<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>

Aturan untuk proyek yang menargetkan kerangka kerja bersama

Kerangka kerja bersama adalah sekumpulan rakitan (file.dll) yang tidak ada di folder aplikasi. Kerangka kerja bersama harus diinstal pada komputer untuk menjalankan aplikasi. Untuk informasi selengkapnya, lihat Kerangka kerja bersama.

ASP.NET Core 2.1 mencakup kerangka kerja bersama berikut:

Versi yang ditentukan oleh referensi paket adalah versi minimum yang diperlukan . Misalnya, proyek yang mereferensikan versi 2.1.1 dari paket ini tidak akan berjalan pada komputer dengan hanya runtime 2.1.0 yang diinstal.

Masalah umum untuk proyek yang menargetkan kerangka kerja bersama:

.NET Core 2.1.300 SDK (pertama kali disertakan dalam Visual Studio 15.6) mengatur versi Microsoft.AspNetCore.App implisit ke 2.1.0 yang menyebabkan konflik dengan Entity Framework Core 2.1.1. Solusi yang direkomendasikan adalah meningkatkan .NET Core SDK ke 2.1.301 atau yang lebih baru. Untuk informasi selengkapnya, lihat Paket yang berbagi dependensi dengan Microsoft.AspNetCore.App tidak dapat mereferensikan versi patch.
Semua proyek yang harus menggunakan Microsoft.AspNetCore.All atau Microsoft.AspNetCore.App harus menambahkan referensi paket untuk paket dalam file proyek, bahkan jika berisi referensi proyek ke proyek lain menggunakan Microsoft.AspNetCore.All atau Microsoft.AspNetCore.App.

Contoh:
- MyApp memiliki referensi paket ke Microsoft.AspNetCore.App.
- MyApp.Tests memiliki referensi proyek ke MyApp.csproj.
Tambahkan referensi paket untuk Microsoft.AspNetCore.App ke MyApp.Tests. Untuk informasi selengkapnya, lihat Pengujian integrasi sulit disiapkan dan mungkin putus pada layanan kerangka kerja bersama.

Memperbarui ke gambar Docker 2.1

Dalam ASP.NET Core 2.1, gambar Docker bermigrasi ke repositori GitHub dotnet/dotnet-docker. Tabel berikut ini memperlihatkan perubahan gambar dan tag 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 Ubah baris di Dockerfile Anda untuk menggunakan nama gambar dan tag baru di kolom 2.1 tabel sebelumnya. Untuk informasi selengkapnya, lihat Migrasi dari repositori docker aspnetcore ke dotnet.

Perubahan untuk memanfaatkan idiom berbasis kode baru yang direkomendasikan di ASP.NET Core 2.1

Perubahan pada Utama

Gambar berikut menunjukkan perubahan yang dilakukan pada file yang dihasilkan Program.cs templat.

old version differences

Gambar sebelumnya menunjukkan versi 2.0 dengan penghapusan berwarna merah.

Gambar berikut menunjukkan kode 2.1. Kode berwarna hijau menggantikan versi 2.0:

new version differences

Kode berikut menunjukkan versi 2.1 dari 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>();
    }
}

Yang baru Main menggantikan panggilan ke BuildWebHost dengan CreateWebHostBuilder. IWebHostBuilderditambahkan untuk mendukung infrastruktur pengujian integrasi baru.

Perubahan pada Startup

Kode berikut menunjukkan perubahan pada kode yang dihasilkan templat 2.1. Semua perubahan adalah kode yang baru ditambahkan, kecuali yang UseBrowserLink telah dihapus:

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

Perubahan kode sebelumnya dirinci dalam:

Dukungan GDPR di ASP.NET Core untuk CookiePolicyOptions dan UseCookiePolicy.
Http Strict Transport Security Protocol (HSTS) untuk UseHsts.
Memerlukan HTTPS untuk UseHttpsRedirection.
SetCompatibilityVersion untuk SetCompatibilityVersion(CompatibilityVersion.Version_2_1).

Perubahan pada kode autentikasi

ASP.NET Core 2.1 menyediakan ASP.NET Core Identity sebagai Razor Pustaka Kelas (RCL).

UI default 2.1 Identity saat ini tidak menyediakan fitur baru yang signifikan melalui versi 2.0. Mengganti Identity dengan paket RCL bersifat opsional. Keuntungan untuk mengganti kode yang dihasilkan Identity templat dengan versi RCL meliputi:

Banyak file yang dipindahkan dari pohon sumber Anda.
Setiap perbaikan bug atau fitur baru untuk Identity disertakan dalam metapackage Microsoft.AspNetCore.App. Anda secara otomatis mendapatkan pembaruan Identity saat Microsoft.AspNetCore.App diperbarui.

Jika Anda telah membuat perubahan non-sepele pada kode yang dihasilkan Identity templat:

Keuntungan sebelumnya mungkin tidak membenarkan konversi ke versi RCL.
Anda dapat menyimpan kode ASP.NET Core 2.0 Identity , kode tersebut didukung sepenuhnya.

Identity2.1 mengekspos titik akhir dengan area .Identity Misalnya, tabel berikut menunjukkan contoh Identity titik akhir yang berubah dari 2.0 menjadi 2.1:

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

Aplikasi yang memiliki kode menggunakan Identity dan mengganti UI 2.0 Identity dengan Pustaka 2.1 Identity perlu memperhitungkan Identity URL memiliki /Identity segmen yang telah ditambahkan ke URI. Salah satu cara untuk menangani titik akhir baru Identity adalah dengan menyiapkan pengalihan, misalnya dari /Account/Login ke /Identity/Account/Login.

Pembaruan Identity ke versi 2.1

Opsi berikut tersedia untuk diperbarui Identity ke 2.1.

Identity Gunakan kode UI 2.0 tanpa perubahan. Menggunakan Identity kode UI 2.0 didukung sepenuhnya. Ini adalah pendekatan yang baik ketika perubahan signifikan telah dilakukan pada kode yang dihasilkan Identity .
Hapus kode 2.0 yang ada Identity dan Perancah Identity ke dalam proyek Anda. Proyek Anda akan menggunakan ASP.NET Core Identity Razor Class Library. Anda dapat membuat kode dan UI untuk salah Identity satu kode UI yang Anda ubah. Terapkan perubahan kode Anda ke kode UI yang baru di-scaffold.
Hapus kode 2.0 dan PerancahIdentityyang ada Identity ke dalam proyek Anda dengan opsi untuk Mengambil alih semua file.

Ganti Identity UI 2.0 dengan Identity Pustaka Kelas 2.1 Razor

Bagian ini menguraikan langkah-langkah untuk mengganti kode yang dihasilkan Identity templat ASP.NET Core 2.0 dengan Pustaka Kelas IntiIdentityRazor ASP.NET. Langkah-langkah berikut adalah untuk Razor proyek Pages, tetapi pendekatan untuk proyek MVC serupa.

Verifikasi bahwa file proyek diperbarui untuk menggunakan versi 2.1
Hapus folder berikut dan semua file di dalamnya:
- Controller
- Halaman/Akun/
- Ekstensi
Bangun proyek.
Perancah Identity ke dalam proyek Anda:
- Pilih proyek yang keluar dari file _Layout.cshtml .
- + Pilih ikon di sisi kanan kelas Konteks data. Terima nama default.
- Pilih Tambahkan untuk membuat kelas konteks Data baru. Membuat konteks data baru diperlukan untuk perancah. Anda menghapus konteks data baru di bagian berikutnya.

Perbarui setelah perancah Identity

Identity Hapus scaffolder yang dihasilkan IdentityDbContext kelas turunan di folder Area/Identity/Data/ .
Hapus Areas/Identity/IdentityHostingStartup.cs.

Perbarui file _LoginPartial.cshtml:

Pindahkan Pages/_LoginPartial.cshtml ke Pages/Shared/_LoginPartial.cshtml.
Tambahkan asp-area="Identity" ke tautan formulir dan jangkar.
<form /> Perbarui elemen ke <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">.

Kode berikut menunjukkan file _LoginPartial.cshtml yang diperbarui:

@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>
}

Perbarui ConfigureServices dengan kode berikut:

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

Perubahan pada Razor file proyek Razor Pages

File tata letak

Pindahkan Pages/_Layout.cshtml ke Pages/Shared/_Layout.cshtml
Di Area/Identity/Pages/_ViewStart.cshtml, ubah Layout = "/Pages/_Layout.cshtml" ke Layout = "/Pages/Shared/_Layout.cshtml".
File _Layout.cshtml memiliki perubahan berikut:
- <partial name="_CookieConsentPartial" /> ditambahkan. Untuk informasi selengkapnya, lihat Dukungan GDPR di ASP.NET Core.
- jQuery berubah dari 2.2.0 menjadi 3.3.1.

_ValidationScriptsPartial.cshtml

Pages/_ValidationScriptsPartial.cshtml berpindah ke Pages/Shared/_ValidationScriptsPartial.cshtml.
jquery.validate/1.14.0 berubah menjadi jquery.validate/1.17.0.

File baru

File berikut ditambahkan:

Privacy.cshtml
Privacy.cshtml.cs

Lihat dukungan GDPR di ASP.NET Core untuk informasi tentang file sebelumnya.

Perubahan pada file proyek Razor MVC

File tata letak

File Layout.cshtml memiliki perubahan berikut:

<partial name="_CookieConsentPartial" /> ditambahkan.
jQuery berubah dari 2.2.0 menjadi 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 perubahan pada jquery.validate/1.17.0

File baru dan metode tindakan

Berikut ini ditambahkan:

Views/Home/Privacy.cshtml
Metode Privacy tindakan ditambahkan ke Home pengontrol.

Lihat dukungan GDPR di ASP.NET Core untuk informasi tentang file sebelumnya.

Perubahan pada file launch Pengaturan.json

Karena aplikasi ASP.NET Core sekarang menggunakan HTTPS secara default, Properties/launchSettings.json file telah berubah.

ON berikut JSmenunjukkan file yang dihasilkan launchSettings.json templat 2.0 sebelumnya:

{
  "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/"
    }
  }
}

ON berikut JSmenunjukkan file baru yang dihasilkan launchSettings.json templat 2.1:

{
  "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"
      }
    }
  }
}

Untuk informasi selengkapnya, lihat Menerapkan HTTPS di ASP.NET Core.

Perubahan mencolok

Header Rentang FileResult

FileResult tidak lagi memproses header Terima-Rentang secara default. Untuk mengaktifkan Accept-Ranges header, atur EnableRangeProcessing ke true.

Header ControllerBase.File dan PhysicalFile Range

Metode berikut ControllerBase tidak lagi memproses header Terima-Rentang secara default:

Kelebihan beban ControllerBase.File
ControllerBase.PhysicalFile

Untuk mengaktifkan Accept-Ranges header, atur parameter ke EnableRangeProcessingtrue.

Modul Inti ASP.NET (ANCM)

Jika ASP.NET Core Module (ANCM) bukan komponen yang dipilih saat Visual Studio diinstal atau jika versi ANCM sebelumnya diinstal pada sistem, unduh Penginstal Bundel Hosting .NET Core terbaru (unduh langsung) dan jalankan alat penginstal. Untuk informasi selengkapnya, lihat Bundel Hosting.

Migrasi dari ASP.NET Core 2.0 ke 2.1

Memperbarui file proyek untuk menggunakan versi 2.1

Aturan untuk proyek yang menargetkan kerangka kerja bersama

Memperbarui ke gambar Docker 2.1

Perubahan untuk memanfaatkan idiom berbasis kode baru yang direkomendasikan di ASP.NET Core 2.1

Perubahan pada Utama

Perubahan pada Startup

Perubahan pada kode autentikasi

Pembaruan Identity ke versi 2.1

Ganti Identity UI 2.0 dengan Identity Pustaka Kelas 2.1 Razor

Perbarui setelah perancah Identity

Perubahan pada Razor file proyek Razor Pages

File tata letak

_ValidationScriptsPartial.cshtml

File baru

Perubahan pada file proyek Razor MVC

File tata letak

_ValidationScriptsPartial.cshtml

File baru dan metode tindakan

Perubahan pada file launch Pengaturan.json

Perubahan mencolok

Header Rentang FileResult

Header ControllerBase.File dan PhysicalFile Range

Modul Inti ASP.NET (ANCM)

Perubahan tambahan

Saran dan Komentar

Sumber Daya Tambahan: