Bermigrasi dari ASP.NET Core 1.x ke 2.0

Artikel
11/30/2023

Dalam artikel ini, kami akan memandu Anda dalam memperbarui proyek ASP.NET Core 1.x yang ada ke ASP.NET Core 2.0. Memigrasikan aplikasi ke ASP.NET Core 2.0 memungkinkan Anda untuk memanfaatkan berbagai fitur baru dan peningkatan performa.

Aplikasi ASP.NET Core 1.x yang ada didasarkan pada template proyek khusus versi. Seiring berkembangnya kerangka kerja ASP.NET Core, begitu juga dengan template proyek dan kode starter yang terkandung di dalamnya. Selain memperbarui kerangka ASP.NET Core, Anda perlu memperbarui kode untuk aplikasi Anda.

Prasyarat

Lihat Memulai menggunakan ASP.NET Core.

Memperbarui Target Framework Moniker (TFM)

Proyek yang menargetkan .NET Core harus menggunakan TFM dari versi yang lebih dari atau sama dengan .NET Core 2.0. Telusuri node <TargetFramework> dalam file .csproj, dan ganti teks dalamnya dengan netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

Proyek yang menargetkan .NET Framework harus menggunakan TFM versi yang lebih dari atau sama dengan .NET Framework 4.6.1. Telusuri node <TargetFramework> dalam file .csproj, dan ganti teks dalamnya dengan net461:

<TargetFramework>net461</TargetFramework>

Catatan

.NET Core 2.0 menawarkan luas permukaan yang jauh lebih besar dari .NET Core 1.x. Jika Anda menargetkan .NET Framework semata-mata karena API yang tidak ada di .NET Core 1.x, penargetan .NET Core 2.0 kemungkinan akan dapat dilakukan.

Jika file proyek berisi <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion>, lihat masalah GitHub ini.

Memperbarui versi .NET Core SDK di global.json

Jika solusi Anda bergantung pada global.json file untuk menargetkan versi .NET Core SDK tertentu, perbarui propertinya version untuk menggunakan versi 2.0 yang diinstal pada komputer Anda:

{
  "sdk": {
    "version": "2.0.0"
  }
}

Memperbarui referensi paket

File .csproj dalam proyek 1.x mencantumkan setiap paket NuGet yang digunakan oleh proyek.

Dalam proyek ASP.NET Core 2.0 yang menargetkan .NET Core 2.0, satu referensi metapackage dalam file .csproj menggantikan kumpulan paket:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

Semua fitur ASP.NET Core 2.0 dan Entity Framework Core 2.0 disertakan dalam metapackage.

Proyek ASP.NET Core 2.0 yang menargetkan .NET Framework harus terus merujuk paket NuGet individual. Perbarui atribut Version dari setiap node <PackageReference /> ke 2.0.0.

Misalnya, berikut adalah daftar node <PackageReference /> yang digunakan dalam proyek ASP.NET Core 2.0 umum yang menargetkan .NET Framework:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

Microsoft.Extensions.CommandLineUtils paket telah dihentikan. Ini masih tersedia tetapi tidak didukung.

Memperbarui alat .NET Core CLI

Dalam file .csproj, perbarui atribut Version dari setiap node <DotNetCliToolReference /> ke 2.0.0.

Misalnya, berikut adalah daftar alat CLI yang digunakan dalam proyek ASP.NET Core 2.0 umum yang menargetkan .NET Core 2.0:

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Mengganti nama properti Fallback Target Paket

File .csproj dari proyek 1.x menggunakan node dan variabel PackageTargetFallback:

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

Ganti nama node dan variabel menjadi AssetTargetFallback:

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Memperbarui metode Utama di Program.cs

Dalam proyek 1.x, metode Main dari Program.cs terlihat seperti ini:

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

Dalam proyek 2.0, metode Main dari Program.cs telah disederhanakan:

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

Adopsi pola 2.0 baru ini sangat disarankan dan diperlukan agar fitur produk seperti Entity Framework (EF) Core Migrations berfungsi. Misalnya, menjalankan Update-Database dari jendela Package Manager Console atau dotnet ef database update dari baris perintah (pada proyek yang dikonversi ke ASP.NET Core 2.0) menghasilkan kesalahan berikut:

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

Menambahkan penyedia konfigurasi

Dalam proyek 1.x, menambahkan penyedia konfigurasi ke aplikasi dilakukan melalui konstruktor Startup. Langkah-langkahnya meliputi pembuatan instans ConfigurationBuilder, memuat penyedia yang berlaku (variabel lingkungan, pengaturan aplikasi, dll.), serta menginisialisasi anggota IConfigurationRoot.

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

Contoh sebelumnya memuat anggota Configuration dengan pengaturan konfigurasi dari appsettings.json serta file appsettings.{Environment}.json apa pun yang cocok dengan properti IHostingEnvironment.EnvironmentName. Lokasi file ini berada di jalur yang sama dengan Startup.cs.

Dalam proyek 2.0, kode konfigurasi boilerplate yang melekat pada proyek 1.x berjalan di belakang layar. Misalnya, variabel lingkungan dan pengaturan aplikasi dimuat saat startup. Kode Startup.cs yang setara dikurangi menjadi inisialisasi IConfiguration dengan instans yang dimasukkan:

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

Untuk menghapus penyedia default yang ditambahkan oleh WebHostBuilder.CreateDefaultBuilder, panggil metode Clear pada properti IConfigurationBuilder.Sources di dalam ConfigureAppConfiguration. Untuk menambahkan kembali penyedia, gunakan metode ConfigureAppConfiguration di Program.cs:

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

Konfigurasi yang digunakan oleh metode CreateDefaultBuilder dalam cuplikan kode sebelumnya dapat dilihat di sini.

Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.

Memindahkan kode inisialisasi database

Dalam proyek 1.x menggunakan EF Core 1.x, perintah seperti dotnet ef migrations add melakukan hal berikut:

Menginisiasi instans Startup
Memanggil metode ConfigureServices untuk mendaftarkan semua layanan dengan injeksi dependensi (termasuk jenis DbContext)
Melakukan tugas yang diperlukan

Dalam 2.0 proyek yang menggunakan EF Core 2.0, Program.BuildWebHost dipanggil untuk mendapatkan layanan aplikasi. Tidak seperti 1.x, ini memiliki efek samping tambahan berupa pemanggilan Startup.Configure. Jika aplikasi 1.x Anda memanggil kode inisialisasi database dalam metode Configure-nya, masalah tak terduga dapat terjadi. Misalnya, jika database belum ada, kode seeding berjalan sebelum EF Core eksekusi perintah Migrasi. Masalah ini menyebabkan perintah dotnet ef migrations list gagal jika database belum ada.

Perhatikan kode inisialisasi seed 1.x berikut dalam metode Configure dari Startup.cs:

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

Dalam proyek 2.0, pindahkan panggilan SeedData.Initialize ke metode Main dari Program.cs:

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

Mulai 2.0, merupakan praktik buruk untuk melakukan apa pun di BuildWebHost, kecuali membangun dan mengonfigurasi host web. Apa pun yang berkaitan dengan menjalankan aplikasi harus ditangani di luar BuildWebHost — biasanya dalam metode Main dari Program.cs.

Meninjau pengaturan kompilasi tampilan Razor

Waktu startup aplikasi yang lebih cepat dan bundel yang diterbitkan yang lebih kecil sangat penting bagi Anda. Untuk alasan ini, kompilasi tampilan Razor diaktifkan secara default di ASP.NET Core 2.0.

Mengatur properti MvcRazorCompileOnPublish ke true tidak lagi diperlukan. Kecuali Anda menonaktifkan kompilasi tampilan, properti ini dapat dihapus dari file .csproj.

Saat menargetkan .NET Framework, Anda masih perlu secara eksplisit merujuk paket NuGet Microsoft.AspNetCore.Mvc.Razor.ViewCompilation di file .csproj:

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

Mengandalkan fitur "light-up" Application Insights

Penyiapan instrumentasi performa aplikasi yang mudah itu penting. Sekarang Anda dapat mengandalkan fitur "light-up" Application Insights baru yang tersedia di alat Visual Studio 2017.

Proyek ASP.NET Core 1.1 yang dibuat di Visual Studio 2017 menambahkan Application Insights secara default. Jika Anda tidak menggunakan Application Insights SDK secara langsung, di luar Program.cs dan Startup.cs, ikuti langkah-langkah berikut:

Jika menargetkan .NET Core, hapus node <PackageReference /> berikut dari file .csproj:

<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />

Jika menargetkan .NET Core, hapus pemanggilan metode ekstensi UseApplicationInsights dari Program.cs:

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

Hapus panggilan API sisi klien Application Insights dari _Layout.cshtml. Ini terdiri dari dua baris kode berikut:

@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)

Jika Anda menggunakan Application Insights SDK secara langsung, lanjutkan menggunakannya. Metapackage 2.0 mencakup versi terbaru dari Application Insights, sehingga kesalahan penurunan tingkat paket akan muncul jika Anda merujuk ke versi yang lebih lama.

Mengadopsi autentikasi/Identity peningkatan

ASP.NET Core 2.0 memiliki model autentikasi baru dan sejumlah perubahan signifikan terhadap Identity ASP.NET Core. Jika Anda membuat proyek dengan Akun Pengguna Individual yang diaktifkan, atau jika Anda telah menambahkan autentikasi atau Identity secara manual, lihat Memigrasikan Autentikasi dan Identity ke ASP.NET Core 2.0.

Sumber Daya Tambahan:

Perubahan yang Melanggar di ASP.NET Core 2.0

Bermigrasi dari ASP.NET Core 1.x ke 2.0

Prasyarat

Memperbarui Target Framework Moniker (TFM)

Memperbarui versi .NET Core SDK di global.json

Memperbarui referensi paket

Memperbarui alat .NET Core CLI

Mengganti nama properti Fallback Target Paket

Memperbarui metode Utama di Program.cs

Menambahkan penyedia konfigurasi

Memindahkan kode inisialisasi database

Meninjau pengaturan kompilasi tampilan Razor

Mengandalkan fitur "light-up" Application Insights

Mengadopsi autentikasi/Identity peningkatan

Sumber Daya Tambahan:

Saran dan Komentar

Sumber Daya Tambahan: