Migrasi dari ASP.NET Core 2.2 ke 3.0
Oleh Scott Addie dan Rick Anderson
Artikel ini menjelaskan cara memperbarui proyek ASP.NET Core 2.2 yang ada ke ASP.NET Core 3.0. Mungkin berguna untuk membuat proyek ASP.NET Core 3.0 baru untuk:
- Bandingkan dengan kode ASP.NET Core 2.2.
- Salin perubahan yang relevan ke proyek ASP.NET Core 3.0 Anda.
Prasyarat
- Visual Studio 2019 dengan beban kerja pengembangan ASP.NET dan web
- .NET Core 3.0 SDK
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
ke versi 3.0 yang diinstal pada komputer Anda:
{
"sdk": {
"version": "3.0.100"
}
}
Memperbarui file proyek
Memperbarui Kerangka Kerja Target
ASP.NET Core 3.0 dan yang lebih baru hanya berjalan pada .NET Core. Atur Moniker Kerangka Kerja Target (TFM) ke netcoreapp3.0
:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>
</Project>
Menghapus referensi paket usang
Sejumlah besar paket NuGet tidak diproduksi untuk ASP.NET Core 3.0. Referensi paket tersebut harus dihapus dari file proyek Anda. Pertimbangkan file proyek berikut untuk aplikasi web ASP.NET Core 2.2:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp2.2</TargetFramework>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.App"/>
<PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
</ItemGroup>
</Project>
File proyek yang diperbarui untuk ASP.NET Core 3.0:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
</PropertyGroup>
</Project>
File proyek ASP.NET Core 3.0 yang diperbarui:
<PropertyGroup>
Dalam :- Memperbarui TFM ke
netcoreapp3.0
<AspNetCoreHostingModel>
Menghapus elemen . Untuk informasi selengkapnya, lihat Model hosting dalam proses dalam dokumen ini.
- Memperbarui TFM ke
<ItemGroup>
Dalam :Microsoft.AspNetCore.App
dihapus. Untuk informasi selengkapnya, lihat Referensi kerangka kerja dalam dokumen ini.Microsoft.AspNetCore.Razor.Design
dihapus dan dalam daftar paket berikut tidak lagi diproduksi.
Untuk melihat daftar lengkap paket yang tidak lagi diproduksi, pilih daftar perluas berikut:
Klik untuk memperluas daftar paket yang tidak lagi diproduksi
- Microsoft.AspNetCore
- Microsoft.AspNetCore.All
- Microsoft.AspNetCore.App
- Microsoft.AspNetCore.Antiforgery
- Microsoft.AspNetCore.Authentication
- Microsoft.AspNetCore.Authentication.Abstractions
- Microsoft.AspNetCore.Authentication.Cookies
- Microsoft.AspNetCore.Authentication.Core
- Microsoft.AspNetCore.Authentication.OAuth
- Microsoft.AspNetCore.Authorization.Policy
- Microsoft.AspNetCore.CookiePolicy
- Microsoft.AspNetCore.Cors
- Microsoft.AspNetCore.Diagnostics
- Microsoft.AspNetCore.Diagnostics.HealthChecks
- Microsoft.AspNetCore.HostFiltering
- Microsoft.AspNetCore.Hosting
- Microsoft.AspNetCore.Hosting.Abstractions
- Microsoft.AspNetCore.Hosting.Server.Abstractions
- Microsoft.AspNetCore.Http
- Microsoft.AspNetCore.Http.Abstractions
- Microsoft.AspNetCore.Http.Connections
- Microsoft.AspNetCore.Http.Extensions
- Microsoft.AspNetCore.HttpOverrides
- Microsoft.AspNetCore.HttpsPolicy
- Microsoft.AspNetCore.Identity
- Microsoft.AspNetCore.Localization
- Microsoft.AspNetCore.Localization.Routing
- Microsoft.AspNetCore.Mvc
- Microsoft.AspNetCore.Mvc.Abstractions
- Microsoft.AspNetCore.Mvc.Analyzers
- Microsoft.AspNetCore.Mvc.ApiExplorer
- Microsoft.AspNetCore.Mvc.Api.Analyzers
- Microsoft.AspNetCore.Mvc.Core
- Microsoft.AspNetCore.Mvc.Cors
- Microsoft.AspNetCore.Mvc.DataAnnotations
- Microsoft.AspNetCore.Mvc.Formatters.Json
- Microsoft.AspNetCore.Mvc.Formatters.Xml
- Microsoft.AspNetCore.Mvc.Localization
- Microsoft.AspNetCore.Mvc.Razor
- Microsoft.AspNetCore.Mvc.Razor. Lihat Kompilasi
- Microsoft.AspNetCore.Mvc.RazorPages
- Microsoft.AspNetCore.Mvc.TagHelpers
- Microsoft.AspNetCore.Mvc.ViewFeatures
- Microsoft.AspNetCore.Razor
- Microsoft.AspNetCore.Razor. Runtime
- Microsoft.AspNetCore.Razor. Desain
- Microsoft.AspNetCore.ResponseCaching
- Microsoft.AspNetCore.ResponseCaching.Abstractions
- Microsoft.AspNetCore.ResponseCompression
- Microsoft.AspNetCore.Rewrite
- Microsoft.AspNetCore.Routing
- Microsoft.AspNetCore.Routing.Abstractions
- Microsoft.AspNetCore.Server.HttpSys
- Microsoft.AspNetCore.Server.IIS
- Microsoft.AspNetCore.Server.IISIntegration
- Microsoft.AspNetCore.Server.Kestrel
- Microsoft.AspNetCore.Server.Kestrel. Inti
- Microsoft.AspNetCore.Server.Kestrel. Https
- Microsoft.AspNetCore.Server.Kestrel. Transport.Abstractions
- Microsoft.AspNetCore.Server.Kestrel. Transport.Sockets
- Microsoft.AspNetCore.Session
- Microsoft.AspNetCore.SignalR
- Microsoft.AspNetCore.SignalR. Inti
- Microsoft.AspNetCore.StaticFiles
- Microsoft.AspNetCore.WebSockets
- Microsoft.AspNetCore.WebUtilities
- Microsoft.Net.Http.Headers
Tinjau perubahan yang melanggar
Tinjau perubahan yang melanggar
Referensi kerangka kerja
Fitur ASP.NET Core yang tersedia melalui salah satu paket yang tercantum di atas tersedia sebagai bagian Microsoft.AspNetCore.App
dari kerangka kerja bersama. Kerangka kerja bersama adalah sekumpulan rakitan (.dll file) yang diinstal pada komputer dan menyertakan komponen runtime dan paket penargetan. Untuk informasi selengkapnya, lihat Kerangka kerja bersama.
Proyek yang menargetkan
Microsoft.NET.Sdk.Web
SDK secara implisit mereferensikanMicrosoft.AspNetCore.App
kerangka kerja.Tidak ada referensi tambahan yang diperlukan untuk proyek-proyek ini:
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp3.0</TargetFramework> </PropertyGroup> ... </Project>
Proyek yang menargetkan
Microsoft.NET.Sdk
atauMicrosoft.NET.Sdk.Razor
SDK, harus menambahkan eksplisitFrameworkReference
keMicrosoft.AspNetCore.App
:<Project Sdk="Microsoft.NET.Sdk.Razor"> <PropertyGroup> <TargetFramework>netcoreapp3.0</TargetFramework> </PropertyGroup> <ItemGroup> <FrameworkReference Include="Microsoft.AspNetCore.App" /> </ItemGroup> ... </Project>
Build yang bergantung pada kerangka kerja menggunakan Docker
Build aplikasi konsol yang bergantung pada kerangka kerja yang menggunakan paket yang bergantung pada kerangka kerja bersama ASP.NET Core dapat memberikan kesalahan runtime berikut:
It was not possible to find any compatible framework version
The specified framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found.
- No frameworks were found.
Microsoft.AspNetCore.App
adalah kerangka kerja bersama yang berisi runtime ASP.NET Core dan hanya ada pada dotnet/core/aspnet
gambar Docker. SDK 3.0 mengurangi ukuran build yang bergantung pada kerangka kerja menggunakan ASP.NET Core dengan tidak menyertakan salinan pustaka duplikat yang tersedia dalam kerangka kerja bersama. Ini adalah potensi penghematan hingga 18 MB, tetapi mengharuskan runtime ASP.NET Core hadir / diinstal untuk menjalankan aplikasi.
Untuk menentukan apakah aplikasi memiliki dependensi (baik langsung atau tidak langsung) pada kerangka kerja bersama ASP.NET Core, periksa runtimeconfig.json
file yang dihasilkan selama build/penerbitan aplikasi Anda. File JSON berikut menunjukkan dependensi pada kerangka kerja bersama ASP.NET Core:
{
"runtimeOptions": {
"tfm": "netcoreapp3.0",
"framework": {
"name": "Microsoft.AspNetCore.App",
"version": "3.0.0"
},
"configProperties": {
"System.GC.Server": true
}
}
}
Jika aplikasi Anda menggunakan Docker, gunakan gambar dasar yang menyertakan ASP.NET Core 3.0. Contohnya,docker pull mcr.microsoft.com/dotnet/core/aspnet:3.0
.
Menambahkan referensi paket untuk rakitan yang dihapus
ASP.NET Core 3.0 menghapus beberapa rakitan yang sebelumnya merupakan bagian Microsoft.AspNetCore.App
dari referensi paket. Untuk memvisualisasikan rakitan mana yang dihapus, bandingkan dua folder kerangka kerja bersama. Misalnya, perbandingan versi 2.2.7 dan 3.0.0:
Untuk terus menggunakan fitur yang disediakan oleh rakitan yang dihapus, referensikan versi 3.0 dari paket yang sesuai:
Aplikasi web yang dihasilkan templat dengan Akun Pengguna Individual memerlukan penambahan paket berikut:
<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>netcoreapp3.0</TargetFramework> <UserSecretsId>My-secret</UserSecretsId> </PropertyGroup> <ItemGroup> <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="3.0.0" /> <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="3.0.0" /> <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="3.0.0" /> <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="3.0.0" /> <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="3.0.0" /> </ItemGroup> </Project>
-
Untuk informasi selengkapnya tentang mereferensikan paket khusus penyedia database, lihat Penyedia Database.
Identity UI
Dukungan untuk Identity UI dapat ditambahkan dengan mereferensikan Microsoft.AspNetCore.Identity. Paket UI .
Layanan SPA
Autentikasi: Dukungan untuk alur autentikasi pihak ketiga tersedia sebagai paket NuGet:
- Facebook OAuth (Microsoft.AspNetCore.Authentication.Facebook)
- Google OAuth (Microsoft.AspNetCore.Authentication.Google)
- Autentikasi Akun Microsoft (Microsoft.AspNetCore.Authentication.MicrosoftAccount)
- Autentikasi OpenID Connect (Microsoft.AspNetCore.Authentication.OpenIdConnect)
- Token pembawa OpenID Connect (Microsoft.AspNetCore.Authentication.JwtBearer)
- Twitter OAuth (Microsoft.AspNetCore.Authentication.Twitter)
- Autentikasi WsFederation (Microsoft.AspNetCore.Authentication.WsFederation)
Dukungan negosiasi pemformatan dan konten untuk
System.Net.HttpClient
: Paket NuGet Microsoft.AspNet.WebApi.Client memberikan ekstensibilitas yang berguna untukSystem.Net.HttpClient
dengan API sepertiReadAsAsync
danPostJsonAsync
. Namun, paket ini tergantung padaNewtonsoft.Json
, bukanSystem.Text.Json
. Itu berarti, misalnya, nama properti serialisasi yang ditentukan olehJsonPropertyNameAttribute
(System.Text.Json
) diabaikan. Ada paket NuGet yang lebih baru yang berisi metode ekstensi serupa tetapi menggunakanSystem.Text.Json
: System.Net.Http.Json.Razor kompilasi runtime: Dukungan untuk kompilasi Razor runtime tampilan dan halaman sekarang menjadi bagian dari Microsoft.AspNetCore.Mvc.Razor. RuntimeCompilation.
Dukungan MVC
Newtonsoft.Json
(Json.NET): Dukungan untuk menggunakan MVC denganNewtonsoft.Json
sekarang menjadi bagianMicrosoft.AspNetCore.Mvc.NewtonsoftJson
dari .
Perubahan startup
Gambar berikut menunjukkan baris yang dihapus dan diubah di aplikasi Web Halaman ASP.NET Core 2.2 Razor :
Pada gambar sebelumnya, kode yang dihapus ditampilkan dengan warna merah. Kode yang dihapus tidak menampilkan cookie kode opsi, yang dihapus sebelum membandingkan file.
Gambar berikut menunjukkan baris yang ditambahkan dan diubah di aplikasi Web Halaman ASP.NET Core 3.0 Razor :
Pada gambar sebelumnya, kode yang ditambahkan ditampilkan dalam warna hijau. Untuk informasi tentang perubahan berikut:
services.AddMvc
keservices.AddRazorPages
, lihat Pendaftaran layanan MVC dalam dokumen ini.CompatibilityVersion
, lihat Versi kompatibilitas untuk ASP.NET Core MVC.IHostingEnvironment
keIWebHostEnvironment
, lihat pengumuman GitHub ini.app.UseAuthorization
ditambahkan ke templat untuk menampilkan middleware otorisasi pesanan harus ditambahkan. Jika aplikasi tidak menggunakan otorisasi, Anda dapat menghapus panggilan dengan aman keapp.UseAuthorization
.app.UseEndpoints
, lihat Razor Pages atau Migrate Startup.Configure dalam dokumen ini.
Dukungan Analyzer
Proyek yang menargetkan Microsoft.NET.Sdk.Web
penganalisis referensi implisit yang sebelumnya dikirim sebagai bagian dari paket Microsoft.AspNetCore.Mvc.Analyzers . Tidak ada referensi tambahan yang diperlukan untuk mengaktifkannya.
Jika aplikasi Anda menggunakan penganalisis API yang sebelumnya dikirim menggunakan paket Microsoft.AspNetCore.Mvc.Api.Analyzers, edit file proyek Anda untuk mereferensikan penganalisis yang dikirim sebagai bagian dari .NET Core Web SDK:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>netcoreapp3.0</TargetFramework>
<IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
</PropertyGroup>
...
</Project>
Razor pustaka kelas
Razor proyek pustaka kelas yang menyediakan komponen UI untuk MVC harus mengatur AddRazorSupportForMvc
properti dalam file proyek:
<PropertyGroup>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
</PropertyGroup>
Model hosting dalam proses
Proyek default ke model hosting dalam proses di ASP.NET Core 3.0 atau yang lebih baru. Anda dapat secara opsional menghapus <AspNetCoreHostingModel>
properti dalam file proyek jika nilainya adalah InProcess
.
Kestrel
Konfigurasi
Migrasikan Kestrel konfigurasi ke penyusun host web yang disediakan oleh ConfigureWebHostDefaults
(Program.cs
):
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.ConfigureKestrel(serverOptions =>
{
// Set properties and call methods on options
})
.UseStartup<Startup>();
});
Jika aplikasi membuat host secara manual dengan ConfigureWebHost
alih-alih ConfigureWebHostDefaults
, panggil UseKestrel
pembangun host web:
public static void Main(string[] args)
{
var host = new HostBuilder()
.UseContentRoot(Directory.GetCurrentDirectory())
.ConfigureWebHost(webBuilder =>
{
webBuilder.UseKestrel(serverOptions =>
{
// Set properties and call methods on options
})
.UseIISIntegration()
.UseStartup<Startup>();
})
.Build();
host.Run();
}
Middleware Koneksi menggantikan Adaptor Koneksi
Adaptor Koneksi (Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter
) telah dihapus dari Kestrel. Ganti Adapter Koneksi dengan Middleware Koneksi. Middleware Koneksi mirip dengan HTTP Middleware di alur ASP.NET Core tetapi untuk koneksi tingkat bawah. HTTPS dan pengelogan koneksi:
- Telah dipindahkan dari Adaptor Koneksi ke Middleware Koneksi.
- Metode ekstensi ini berfungsi seperti pada versi ASP.NET Core sebelumnya.
Untuk informasi selengkapnya, lihat contoh TlsFilterConnectionHandler di bagian ListenOptions.Protocols di artikel.Kestrel
Abstraksi transportasi dipindahkan dan dipublikasikan
Lapisan Kestrel transportasi telah diekspos sebagai antarmuka publik di Connections.Abstractions
. Sebagai bagian dari pembaruan ini:
Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions
dan jenis terkait telah dihapus.- NoDelay dipindahkan dari ListenOptions ke opsi transportasi.
Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions.Internal.SchedulingMode
dihapus dari KestrelServerOptions.
Untuk informasi selengkapnya, lihat sumber daya GitHub berikut ini:
- Abstraksi jaringan klien/server (dotnet/AspNetCore #10308)
- Terapkan abstraksi pendengar bedrock baru dan plat Kestrel ulang di atas (dotnet/AspNetCore #10321)
Kestrel Meminta header trailer
Untuk aplikasi yang menargetkan versi ASP.NET Core yang lebih lama:
- Kestrel menambahkan header trailer terpotong HTTP/1.1 ke dalam koleksi header permintaan.
- Trailer tersedia setelah isi permintaan dibaca hingga akhir.
Ini menyebabkan beberapa kekhawatiran tentang ambiguitas antara header dan trailer, sehingga trailer telah dipindahkan ke koleksi baru (RequestTrailerExtensions
) di 3.0.
Trailer permintaan HTTP/2 adalah:
- Tidak tersedia di ASP.NET Core 2.2.
- Tersedia dalam 3.0 sebagai
RequestTrailerExtensions
.
Metode ekstensi permintaan baru hadir untuk mengakses trailer ini. Seperti halnya HTTP/1.1, trailer tersedia setelah isi permintaan dibaca hingga akhir.
Untuk rilis 3.0, metode berikut RequestTrailerExtensions
tersedia:
GetDeclaredTrailers
: Mendapatkan header permintaanTrailer
yang mencantumkan trailer mana yang diharapkan setelah isi.SupportsTrailers
: Menunjukkan apakah permintaan mendukung penerimaan header trailer.CheckTrailersAvailable
: Memeriksa apakah permintaan mendukung trailer dan apakah mereka tersedia untuk dibaca. Pemeriksaan ini tidak mengasumsikan bahwa ada trailer yang akan dibaca. Mungkin tidak ada trailer untuk dibaca bahkan jikatrue
dikembalikan oleh metode ini.GetTrailer
: Mendapatkan header berikutnya yang diminta dari respons. PeriksaSupportsTrailers
sebelum memanggilGetTrailer
, atau NotSupportedException mungkin terjadi jika permintaan tidak mendukung header berikutnya.
Untuk informasi selengkapnya, lihat Menempatkan trailer permintaan dalam koleksi terpisah (dotnet/AspNetCore #10410).
AllowSynchronousIO dinonaktifkan
AllowSynchronousIO
mengaktifkan atau menonaktifkan API I/O sinkron, seperti HttpRequest.Body.Read
, , HttpResponse.Body.Write
dan Stream.Flush
. API ini adalah sumber kelaparan utas yang menyebabkan crash aplikasi. Dalam 3.0, AllowSynchronousIO
dinonaktifkan secara default. Untuk informasi selengkapnya, lihat bagian I/O Sinkron di Kestrel artikel.
Jika I/O sinkron diperlukan, I/O dapat diaktifkan dengan mengonfigurasi AllowSynchronousIO
opsi pada server yang digunakan (saat memanggil ConfigureKestrel
, misalnya, jika menggunakan Kestrel). Perhatikan bahwa server (Kestrel, HttpSys, TestServer, dll.) semuanya memiliki opsi mereka sendiri AllowSynchronousIO
yang tidak akan memengaruhi server lain. I/O sinkron dapat diaktifkan untuk semua server berdasarkan per permintaan menggunakan IHttpBodyControlFeature.AllowSynchronousIO
opsi :
var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
syncIOFeature.AllowSynchronousIO = true;
}
Jika Anda mengalami masalah dengan TextWriter implementasi atau aliran lain yang memanggil API sinkron di Buang, panggil API baru DisposeAsync sebagai gantinya.
Untuk informasi selengkapnya, lihat [Pengumuman] AllowSynchronousIO dinonaktifkan di semua server (dotnet/AspNetCore #7644).
Buffering formatter output
Newtonsoft.Json, XmlSerializer, dan DataContractSerializer formatter output berbasis hanya mendukung serialisasi sinkron. Untuk memungkinkan formatter ini bekerja dengan pembatasan AllowSynchronousIO server, MVC buffer output dari formatter ini sebelum menulis ke disk. Sebagai hasil dari buffering, MVC akan menyertakan header Content-Length saat merespons menggunakan formatter ini.
System.Text.Json mendukung serialisasi asinkron dan akibatnya System.Text.Json
formatter berbasis tidak buffer. Pertimbangkan untuk menggunakan formatter ini untuk meningkatkan performa.
Untuk menonaktifkan buffering, aplikasi dapat mengonfigurasi SuppressOutputFormatterBuffering dalam startup mereka:
services.AddControllers(options => options.SuppressOutputFormatterBuffering = true)
Perhatikan bahwa ini dapat mengakibatkan aplikasi melemparkan pengecualian runtime jika AllowSynchronousIO
tidak juga dikonfigurasi.
Microsoft.AspNetCore.Server.Kestrel. Rakitan Https dihapus
Di ASP.NET Core 2.1, konten Microsoft.AspNetCore.Server.Kestrel. Https.dll dipindahkan ke Microsoft.AspNetCore.Server.Kestrel. Core.dll. Ini adalah pembaruan yang tidak melanggar menggunakan TypeForwardedTo
atribut. Untuk 3.0, Microsoft.AspNetCore.Server kosong .Kestrel. Https.dll assembly dan paket NuGet telah dihapus.
Pustaka yang mereferensikan Microsoft.AspNetCore.Server.Kestrel. Https harus memperbarui dependensi ASP.NET Core ke 2.1 atau yang lebih baru.
Aplikasi dan pustaka yang menargetkan ASP.NET Core 2.1 atau yang lebih baru harus menghapus referensi langsung apa pun ke Microsoft.AspNetCore.Server.Kestrel. Paket Https .
Dukungan Newtonsoft.Json (Json.NET)
Sebagai bagian dari pekerjaan untuk meningkatkan kerangka kerja bersama ASP.NET Core, Newtonsoft.Json (Json.NET) telah dihapus dari kerangka kerja bersama ASP.NET Core.
Serializer JSON default untuk ASP.NET Core sekarang System.Text.Json, yang baru di .NET Core 3.0. Pertimbangkan untuk menggunakan System.Text.Json
jika memungkinkan. Ini berkinerja tinggi dan tidak memerlukan dependensi pustaka tambahan. Namun, karena System.Text.Json
baru, mungkin saat ini fitur yang dibutuhkan aplikasi Anda hilang. Untuk informasi selengkapnya, lihat Cara bermigrasi dari Newtonsoft.Json ke System.Text.Json.
Menggunakan Newtonsoft.Json dalam proyek ASP.NET Core 3.0 SignalR
Instal Microsoft.AspNetCore.SignalR. Paket Protocols.NewtonsoftJson NuGet.
Pada klien, rantai
AddNewtonsoftJsonProtocol
panggilan metode keHubConnectionBuilder
instans:new HubConnectionBuilder() .WithUrl("/chathub") .AddNewtonsoftJsonProtocol(...) .Build();
Di server, rantai
AddNewtonsoftJsonProtocol
panggilan metode keAddSignalR
panggilan metode diStartup.ConfigureServices
:services.AddSignalR() .AddNewtonsoftJsonProtocol(...);
Menggunakan Newtonsoft.Json dalam proyek MVC ASP.NET Core 3.0
Pasang paket
Microsoft.AspNetCore.Mvc.NewtonsoftJson
.Perbarui
Startup.ConfigureServices
untuk memanggilAddNewtonsoftJson
.services.AddMvc() .AddNewtonsoftJson();
AddNewtonsoftJson
kompatibel dengan metode pendaftaran layanan MVC baru:AddRazorPages
AddControllersWithViews
AddControllers
services.AddControllers() .AddNewtonsoftJson();
Newtonsoft.Json
pengaturan dapat diatur dalam panggilan keAddNewtonsoftJson
:services.AddMvc() .AddNewtonsoftJson(options => options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver());
Catatan: Jika
AddNewtonsoftJson
metode tidak tersedia, pastikan Anda menginstalMicrosoft.AspNetCore.Mvc.NewtonsoftJson
paket. Kesalahan umum adalah menginstal paket Newtonsoft.Json alih-alihMicrosoft.AspNetCore.Mvc.NewtonsoftJson
paket.
Untuk informasi selengkapnya, lihat Menambahkan dukungan format JSON berbasis Newtonsoft.Json.
Pendaftaran layanan MVC
ASP.NET Core 3.0 menambahkan opsi baru untuk mendaftarkan skenario MVC di dalam Startup.ConfigureServices
.
Tiga metode ekstensi tingkat atas baru yang terkait dengan skenario IServiceCollection
MVC tersedia. Templat menggunakan metode baru ini alih-alih AddMvc
. Namun, AddMvc
terus berulah seperti yang ada di rilis sebelumnya.
Contoh berikut menambahkan dukungan untuk pengontrol dan fitur terkait API, tetapi bukan tampilan atau halaman. Templat API menggunakan kode ini:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
}
Contoh berikut menambahkan dukungan untuk pengontrol, fitur terkait API, dan tampilan, tetapi bukan halaman. Templat Aplikasi Web (MVC) menggunakan kode ini:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
}
Contoh berikut menambahkan dukungan untuk Razor Pages dan dukungan pengontrol minimal. Templat Aplikasi Web menggunakan kode ini:
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
}
Metode baru juga dapat digabungkan. Contoh berikut setara dengan panggilan AddMvc
di ASP.NET Core 2.2:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllersWithViews();
services.AddRazorPages();
}
Kode startup perutean
Jika aplikasi memanggil UseMvc
atau UseSignalR
, migrasikan aplikasi ke Perutean Titik Akhir jika memungkinkan. Untuk meningkatkan kompatibilitas Perutean Titik Akhir dengan versi MVC sebelumnya, kami telah mengembalikan beberapa perubahan dalam pembuatan URL yang diperkenalkan di ASP.NET Core 2.2. Jika Anda mengalami masalah saat menggunakan Perutean Titik Akhir di 2.2, harapkan peningkatan di ASP.NET Core 3.0 dengan pengecualian berikut:
- Jika aplikasi menerapkan
IRouter
atau mewarisi dariRoute
, gunakan DynamicRouteValuesTransformer sebagai pengganti. - Jika aplikasi langsung mengakses
RouteData.Routers
di dalam MVC untuk mengurai URL, Anda dapat menggantinya dengan penggunaan LinkParser.ParsePathByEndpointName.- Tentukan rute dengan nama rute.
- Gunakan
LinkParser.ParsePathByEndpointName
dan berikan nama rute yang diinginkan.
Perutean Titik Akhir mendukung sintaks pola rute yang sama dan fitur penulisan pola rute sebagai IRouter
. Perutean Titik Akhir mendukung IRouteConstraint
. Perutean titik akhir mendukung [Route]
, [HttpGet]
, dan atribut perutean MVC lainnya.
Untuk sebagian besar aplikasi, hanya Startup
memerlukan perubahan.
Memigrasikan Startup.Configure
Saran umum:
Tambahkan
UseRouting
.Jika aplikasi memanggil
UseStaticFiles
, tempatkanUseStaticFiles
sebelumUseRouting
.Jika aplikasi menggunakan fitur autentikasi/otorisasi seperti
AuthorizePage
atau , lakukan panggilan keUseAuthentication
danUseAuthorization
: setelah,UseRouting
danUseCors
, tetapi sebelumUseEndpoints
[Authorize]
:public void Configure(IApplicationBuilder app) { ... app.UseStaticFiles(); app.UseRouting(); app.UseCors(); app.UseAuthentication(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); });
Ganti
UseMvc
atauUseSignalR
denganUseEndpoints
.Jika aplikasi menggunakan skenario CORS , seperti
[EnableCors]
, lakukan panggilan keUseCors
sebelum middleware lain yang menggunakan CORS (misalnya, tempatkanUseCors
sebelumUseAuthentication
,UseAuthorization
, danUseEndpoints
).Ganti
IHostingEnvironment
denganIWebHostEnvironment
dan tambahkanusing
pernyataan untuk Microsoft.AspNetCore.Hosting namespace.Ganti
IApplicationLifetime
dengan IHostApplicationLifetime (Microsoft.Extensions.Hosting namespace).Ganti
EnvironmentName
dengan Environments (Microsoft.Extensions.Hosting namespace).
Kode berikut adalah contoh Startup.Configure
dalam aplikasi ASP.NET Core 2.2 yang khas:
public void Configure(IApplicationBuilder app)
{
...
app.UseStaticFiles();
app.UseAuthentication();
app.UseSignalR(hubs =>
{
hubs.MapHub<ChatHub>("/chat");
});
app.UseMvc(routes =>
{
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
}
Setelah memperbarui kode sebelumnya Startup.Configure
:
public void Configure(IApplicationBuilder app)
{
...
app.UseStaticFiles();
app.UseRouting();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>("/chat");
endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
}
Peringatan
Untuk sebagian besar aplikasi, panggilan ke UseAuthentication
, UseAuthorization
, dan UseCors
harus muncul antara panggilan ke UseRouting
dan UseEndpoints
agar efektif.
Pemeriksaan Kesehatan
Pemeriksaan Kesehatan menggunakan perutean titik akhir dengan Host Generik. Di Startup.Configure
, panggil MapHealthChecks
pembangun titik akhir dengan URL titik akhir atau jalur relatif:
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/health");
});
Titik akhir Pemeriksaan Kesehatan dapat:
- Tentukan satu atau beberapa host/port yang diizinkan.
- Memerlukan otorisasi.
- Memerlukan CORS.
Untuk informasi lebih lanjut, lihat Pemeriksaan kondisi di ASP.NET Core.
Panduan middleware keamanan
Dukungan untuk otorisasi dan CORS disatukan di sekitar pendekatan middleware . Ini memungkinkan penggunaan middleware dan fungsionalitas yang sama di seluruh skenario ini. Middleware otorisasi yang diperbarui disediakan dalam rilis ini, dan CORS Middleware ditingkatkan sehingga dapat memahami atribut yang digunakan oleh pengontrol MVC.
CORS
Sebelumnya, CORS mungkin sulit dikonfigurasi. Middleware disediakan untuk digunakan dalam beberapa kasus penggunaan, tetapi filter MVC dimaksudkan untuk digunakan tanpa middleware dalam kasus penggunaan lainnya. Dengan ASP.NET Core 3.0, sebaiknya semua aplikasi yang memerlukan CORS menggunakan CORS Middleware bersama dengan Perutean Titik Akhir. UseCors
dapat diberikan kebijakan default, dan [EnableCors]
[DisableCors]
atribut dapat digunakan untuk mengambil alih kebijakan default jika diperlukan.
Dalam contoh berikut:
- CORS diaktifkan untuk semua titik akhir dengan
default
kebijakan bernama. - Kelas
MyController
menonaktifkan CORS dengan[DisableCors]
atribut .
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseCors("default");
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
[DisableCors]
public class MyController : ControllerBase
{
...
}
Authorization
Dalam versi ASP.NET Core yang lebih lama, dukungan otorisasi disediakan melalui [Authorize]
atribut . Middleware otorisasi tidak tersedia. Di ASP.NET Core 3.0, middleware otorisasi diperlukan. Sebaiknya tempatkan Middleware Otorisasi Inti ASP.NET (UseAuthorization
) segera setelah UseAuthentication
. Middleware Otorisasi juga dapat dikonfigurasi dengan kebijakan default, yang dapat ditimpa.
Di ASP.NET Core 3.0 atau yang lebih baru, UseAuthorization
dipanggil di Startup.Configure
, dan berikut ini HomeController
memerlukan pengguna yang masuk:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
public class HomeController : Controller
{
[Authorize]
public IActionResult BuyWidgets()
{
...
}
}
Saat menggunakan perutean titik akhir, kami sarankan untuk tidak mengonfigurasi AuthorizeFilter dan sebaliknya mengandalkan middleware Otorisasi. Jika aplikasi menggunakan AuthorizeFilter
sebagai filter global di MVC, sebaiknya refaktor kode untuk memberikan kebijakan dalam panggilan ke AddAuthorization
.
DefaultPolicy
awalnya dikonfigurasi untuk memerlukan autentikasi, jadi tidak diperlukan konfigurasi tambahan. Dalam contoh berikut, titik akhir MVC ditandai sebagai RequireAuthorization
sehingga semua permintaan harus diotorisasi berdasarkan DefaultPolicy
. Namun, akses yang HomeController
diizinkan tanpa pengguna masuk ke aplikasi karena [AllowAnonymous]
:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute().RequireAuthorization();
});
}
[AllowAnonymous]
public class HomeController : Controller
{
...
}
Otorisasi untuk titik akhir tertentu
Otorisasi juga dapat dikonfigurasi untuk kelas titik akhir tertentu. Kode berikut adalah contoh mengonversi aplikasi MVC yang mengonfigurasi global AuthorizeFilter
ke aplikasi dengan kebijakan tertentu yang memerlukan otorisasi:
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
static readonly string _RequireAuthenticatedUserPolicy =
"RequireAuthenticatedUserPolicy";
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>(
options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
// Pre 3.0:
// services.AddMvc(options => options.Filters.Add(new AuthorizeFilter(...));
services.AddControllersWithViews();
services.AddRazorPages();
services.AddAuthorization(o => o.AddPolicy(_RequireAuthenticatedUserPolicy,
builder => builder.RequireAuthenticatedUser()));
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute()
.RequireAuthorization(_RequireAuthenticatedUserPolicy);
endpoints.MapRazorPages();
});
}
}
Kebijakan juga dapat disesuaikan. dikonfigurasi DefaultPolicy
untuk memerlukan autentikasi:
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<ApplicationDbContext>(options =>
options.UseSqlServer(
Configuration.GetConnectionString("DefaultConnection")));
services.AddDefaultIdentity<IdentityUser>(
options => options.SignIn.RequireConfirmedAccount = true)
.AddEntityFrameworkStores<ApplicationDbContext>();
services.AddControllersWithViews();
services.AddRazorPages();
services.AddAuthorization(options =>
{
options.DefaultPolicy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
});
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseDatabaseErrorPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute().RequireAuthorization();
endpoints.MapRazorPages();
});
}
}
[AllowAnonymous]
public class HomeController : Controller
{
Atau, semua titik akhir dapat dikonfigurasi untuk memerlukan otorisasi tanpa [Authorize]
atau RequireAuthorization
dengan mengonfigurasi FallbackPolicy
. FallbackPolicy
berbeda dari DefaultPolicy
. dipicu DefaultPolicy
oleh [Authorize]
atau RequireAuthorization
, saat FallbackPolicy
dipicu ketika tidak ada kebijakan lain yang ditetapkan. FallbackPolicy
awalnya dikonfigurasi untuk mengizinkan permintaan tanpa otorisasi.
Contoh berikut sama dengan contoh sebelumnya DefaultPolicy
tetapi menggunakan FallbackPolicy
untuk selalu memerlukan autentikasi pada semua titik akhir kecuali ketika [AllowAnonymous]
ditentukan:
public void ConfigureServices(IServiceCollection services)
{
...
services.AddAuthorization(options =>
{
options.FallbackPolicy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
});
}
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapDefaultControllerRoute();
});
}
[AllowAnonymous]
public class HomeController : Controller
{
...
}
Otorisasi oleh middleware berfungsi tanpa kerangka kerja memiliki pengetahuan khusus tentang otorisasi. Misalnya, pemeriksaan kesehatan tidak memiliki pengetahuan khusus tentang otorisasi, tetapi pemeriksaan kesehatan dapat memiliki kebijakan otorisasi yang dapat dikonfigurasi yang diterapkan oleh middleware.
Selain itu, setiap titik akhir dapat menyesuaikan persyaratan otorisasinya. Dalam contoh berikut, UseAuthorization
memproses otorisasi dengan DefaultPolicy
, tetapi /healthz
titik akhir pemeriksaan kesehatan memerlukan admin
pengguna:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints
.MapHealthChecks("/healthz")
.RequireAuthorization(new AuthorizeAttribute(){ Roles = "admin", });
});
}
Perlindungan diimplementasikan untuk beberapa skenario. Middleware Titik Akhir melemparkan pengecualian jika kebijakan otorisasi atau CORS dilewati karena middleware yang hilang. Dukungan Penganalisis untuk memberikan umpan balik tambahan tentang kesalahan konfigurasi sedang berlangsung.
Penangan otorisasi kustom
Jika aplikasi menggunakan handler otorisasi kustom, perutean titik akhir meneruskan jenis sumber daya yang berbeda ke handler daripada MVC. Handler yang mengharapkan sumber daya konteks handler otorisasi berjenis AuthorizationFilterContext(jenis sumber daya yang disediakan oleh filter MVC) perlu diperbarui untuk menangani sumber daya jenis RouteEndpoint (jenis sumber daya yang diberikan kepada penangan otorisasi oleh perutean titik akhir).
MVC masih menggunakan AuthorizationFilterContext
sumber daya, jadi jika aplikasi menggunakan filter otorisasi MVC bersama dengan otorisasi perutean titik akhir, mungkin perlu untuk menangani kedua jenis sumber daya.
SignalR
Pemetaan SignalR hub sekarang terjadi di dalam UseEndpoints
.
Petakan setiap hub dengan MapHub
. Seperti pada versi sebelumnya, setiap hub secara eksplisit tercantum.
Dalam contoh berikut, dukungan untuk ChatHub
SignalR hub ditambahkan:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHub<ChatHub>();
});
}
Ada opsi baru untuk mengontrol batas ukuran pesan dari klien. Misalnya, dalam Startup.ConfigureServices
:
services.AddSignalR(hubOptions =>
{
hubOptions.MaximumReceiveMessageSize = 32768;
});
Dalam ASP.NET Core 2.2, Anda dapat mengatur TransportMaxBufferSize
dan yang akan secara efektif mengontrol ukuran pesan maksimum. Dalam ASP.NET Core 3.0, opsi itu sekarang hanya mengontrol ukuran maksimum sebelum backpressure diamati.
SignalR rakitan dalam kerangka kerja bersama
ASP.NET rakitan sisi server Core SignalR sekarang diinstal dengan .NET Core SDK. Untuk informasi selengkapnya, lihat Menghapus referensi paket usang dalam dokumen ini.
Pengontrol MVC
Pemetaan pengontrol sekarang terjadi di dalam UseEndpoints
.
Tambahkan MapControllers
jika aplikasi menggunakan perutean atribut. Karena perutean mencakup dukungan untuk banyak kerangka kerja di ASP.NET Core 3.0 atau yang lebih baru, menambahkan pengontrol yang dirutekan atribut adalah keikutsertaan.
Ganti yang berikut ini:
MapRoute
denganMapControllerRoute
MapAreaRoute
denganMapAreaControllerRoute
Karena perutean sekarang mencakup dukungan untuk lebih dari sekadar MVC, terminologi telah berubah untuk membuat metode ini dengan jelas menyatakan apa yang mereka lakukan. Rute konvensional seperti MapControllerRoute
//MapAreaControllerRoute
MapDefaultControllerRoute
diterapkan dalam urutan ditambahkan. Tempatkan rute yang lebih spesifik (seperti rute untuk suatu area) terlebih dahulu.
Dalam contoh berikut:
MapControllers
menambahkan dukungan untuk pengontrol yang dirutekan atribut.MapAreaControllerRoute
menambahkan rute konvensional untuk pengontrol di suatu area.MapControllerRoute
menambahkan rute konvensional untuk pengontrol.
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.MapAreaControllerRoute(
"admin",
"admin",
"Admin/{controller=Home}/{action=Index}/{id?}");
endpoints.MapControllerRoute(
"default", "{controller=Home}/{action=Index}/{id?}");
});
}
Penghapusan akhiran asinkron dari nama tindakan pengontrol
Di ASP.NET Core 3.0, ASP.NET Core MVC menghapus Async
akhiran dari nama tindakan pengontrol. Perutean dan pembuatan tautan terpengaruh oleh default baru ini. Contohnya:
public class ProductsController : Controller
{
public async Task<IActionResult> ListAsync()
{
var model = await _dbContext.Products.ToListAsync();
return View(model);
}
}
Sebelum ASP.NET Core 3.0:
Tindakan sebelumnya dapat diakses di rute Products/ListAsync .
Pembuatan tautan diperlukan untuk menentukan akhiran
Async
. Contohnya:<a asp-controller="Products" asp-action="ListAsync">List</a>
Di ASP.NET Core 3.0:
Tindakan sebelumnya dapat diakses di rute Produk/Daftar .
Pembuatan tautan tidak memerlukan penentuan akhiran
Async
. Contohnya:<a asp-controller="Products" asp-action="List">List</a>
Perubahan ini tidak memengaruhi nama yang ditentukan menggunakan [ActionName]
atribut . Perilaku default dapat dinonaktifkan dengan kode berikut di Startup.ConfigureServices
:
services.AddMvc(options =>
options.SuppressAsyncSuffixInActionNames = false);
Perubahan pada pembuatan tautan
Ada beberapa perbedaan dalam pembuatan tautan (menggunakan Url.Link
dan API serupa, misalnya). Ini termasuk:
- Secara default, saat menggunakan perutean titik akhir, casing parameter rute dalam URI yang dihasilkan belum tentu dipertahankan. Perilaku ini dapat dikontrol dengan
IOutboundParameterTransformer
antarmuka. - Membuat URI untuk rute yang tidak valid (pengontrol/tindakan atau halaman yang tidak ada) akan menghasilkan string kosong di bawah perutean titik akhir alih-alih menghasilkan URI yang tidak valid.
- Nilai sekitar (parameter rute dari konteks saat ini) tidak secara otomatis digunakan dalam pembuatan tautan dengan perutean titik akhir. Sebelumnya, saat membuat tautan ke tindakan lain (atau halaman), nilai rute yang tidak ditentukan akan disimpulkan dari nilai sekitar rute saat ini . Saat menggunakan perutean titik akhir, semua parameter rute harus ditentukan secara eksplisit selama pembuatan tautan.
Razor Pages
Halaman Pemetaan Razor sekarang berlangsung di dalam UseEndpoints
.
Tambahkan MapRazorPages
jika aplikasi menggunakan Razor Pages. Karena Perutean Titik Akhir menyertakan dukungan untuk banyak kerangka kerja, menambahkan Razor Pages sekarang ikut serta.
Dalam metode berikut Startup.Configure
, MapRazorPages
menambahkan dukungan untuk Razor Pages:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
Menggunakan MVC tanpa Perutean Titik Akhir
Menggunakan MVC melalui UseMvc
atau UseMvcWithDefaultRoute
di ASP.NET Core 3.0 memerlukan keikutsertaan eksplisit di dalam Startup.ConfigureServices
. Hal ini diperlukan karena MVC harus mengetahui apakah MVC dapat mengandalkan otorisasi dan CORS Middleware selama inisialisasi. Penganalisis disediakan yang memperingatkan jika aplikasi mencoba menggunakan konfigurasi yang tidak didukung.
Jika aplikasi memerlukan dukungan warisan IRouter
, nonaktifkan EnableEndpointRouting
menggunakan salah satu pendekatan berikut di Startup.ConfigureServices
:
services.AddMvc(options => options.EnableEndpointRouting = false);
services.AddControllers(options => options.EnableEndpointRouting = false);
services.AddControllersWithViews(options => options.EnableEndpointRouting = false);
services.AddRazorPages().AddMvcOptions(options => options.EnableEndpointRouting = false);
Pemeriksaan kesehatan
Pemeriksaan kesehatan dapat digunakan sebagai router-ware dengan Perutean Titik Akhir.
Tambahkan MapHealthChecks
untuk menggunakan pemeriksaan kesehatan dengan Perutean Titik Akhir. Metode MapHealthChecks
menerima argumen yang mirip UseHealthChecks
dengan . Keuntungan menggunakan MapHealthChecks
lebih UseHealthChecks
dari adalah kemampuan untuk menerapkan otorisasi dan memiliki kontrol yang lebih halus atas kebijakan pencocokan.
Dalam contoh berikut, MapHealthChecks
dipanggil untuk titik akhir pemeriksaan kesehatan di /healthz
:
public void Configure(IApplicationBuilder app)
{
...
app.UseRouting();
app.UseEndpoints(endpoints =>
{
endpoints.MapHealthChecks("/healthz", new HealthCheckOptions() { });
});
}
HostBuilder menggantikan WebHostBuilder
Templat ASP.NET Core 3.0 menggunakan Host Generik. Versi sebelumnya menggunakan Web Host. Kode berikut menunjukkan kelas yang dihasilkan Program
templat ASP.NET Core 3.0:
// requires using Microsoft.AspNetCore.Hosting;
// requires using Microsoft.Extensions.Hosting;
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
Kode berikut menunjukkan kelas yang dihasilkan Program
templat ASP.NET Core 2.2:
public class Program
{
public static void Main(string[] args)
{
CreateWebHostBuilder(args).Build().Run();
}
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
.UseStartup<Startup>();
}
IWebHostBuilder tetap dalam 3.0 dan merupakan jenis yang webBuilder
terlihat dalam sampel kode sebelumnya. WebHostBuilder akan ditolak dalam rilis mendatang dan digantikan oleh HostBuilder
.
Perubahan paling signifikan dari WebHostBuilder
ke adalah dalam injeksi dependensi (DI)HostBuilder
. Saat menggunakan HostBuilder
, Anda hanya dapat menyuntikkan yang berikut ini ke dalam Startup
konstruktor :
Batasan HostBuilder
DI:
- Aktifkan kontainer DI untuk dibangun hanya satu kali.
- Menghindari masalah masa pakai objek yang dihasilkan seperti menyelesaikan beberapa instans singleton.
Untuk informasi selengkapnya, lihat Menghindari injeksi layanan Startup di ASP.NET Core 3.
TambahkanAuthorization dipindahkan ke rakitan yang berbeda
Metode ASP.NET Core 2.2 dan yang lebih rendah AddAuthorization
dalam Microsoft.AspNetCore.Authorization.dll:
- Telah diganti
AddAuthorizationCore
namanya . - Telah dipindahkan ke Microsoft.AspNetCore.Authorization.Policy.dll.
Aplikasi yang menggunakan Microsoft.AspNetCore.Authorization.dll dan Microsoft.AspNetCore.Authorization.Policy.dll tidak terpengaruh.
Aplikasi yang tidak menggunakan Microsoft.AspNetCore.Authorization.Policy.dll harus melakukan salah satu hal berikut:
- Tambahkan referensi ke Microsoft.AspNetCore.Authorization.Policy.dll. Pendekatan ini berfungsi untuk sebagian besar aplikasi dan hanya itu yang diperlukan.
- Beralih menggunakan
AddAuthorizationCore
Untuk informasi selengkapnya, lihat Melanggar perubahan dalam AddAuthorization(o =>
) overload tinggal di rakitan yang berbeda #386.
Identity UI
Identity Pembaruan UI untuk ASP.NET Core 3.0:
- Tambahkan referensi paket ke Microsoft.AspNetCore.Identity. UI.
- Aplikasi yang tidak menggunakan Razor Pages harus memanggil
MapRazorPages
. Lihat Razor Halaman dalam dokumen ini. - Bootstrap 4 adalah kerangka kerja UI default. Atur
IdentityUIFrameworkVersion
properti proyek untuk mengubah default. Untuk informasi selengkapnya, lihat pengumuman GitHub ini.
SignalR
Klien SignalR JavaScript telah berubah dari @aspnet/signalr
menjadi @microsoft/signalr
. Untuk bereaksi terhadap perubahan ini, ubah referensi dalam package.json
file, require
pernyataan, dan pernyataan ECMAScript import
.
System.Text.Json adalah protokol default
System.Text.Json
sekarang menjadi protokol Hub default yang digunakan oleh klien dan server.
Di Startup.ConfigureServices
, panggil AddJsonProtocol
untuk mengatur opsi serializer.
Server:
services.AddSignalR(...)
.AddJsonProtocol(options =>
{
options.PayloadSerializerOptions.WriteIndented = false;
})
Klien:
new HubConnectionBuilder()
.WithUrl("/chathub")
.AddJsonProtocol(options =>
{
options.PayloadSerializerOptions.WriteIndented = false;
})
.Build();
Beralih ke Newtonsoft.Json
Jika Anda menggunakan fitur Newtonsoft.Json yang tidak didukung di System.Text.Json, Anda dapat beralih kembali ke Newtonsoft.Json
. Lihat Menggunakan Newtonsoft.Json dalam proyek ASP.NET Core 3.0 SignalR sebelumnya di artikel ini.
Cache terdistribusi Redis
Paket Microsoft.Extensions.Caching.Redis tidak tersedia untuk aplikasi ASP.NET Core 3.0 atau yang lebih baru. Ganti referensi paket dengan Microsoft.Extensions.Caching.StackExchangeRedis. Untuk informasi selengkapnya, lihat Penembolokan terdistribusi di ASP.NET Core.
Ikut serta dalam kompilasi runtime
Sebelum ASP.NET Core 3.0, kompilasi runtime tampilan adalah fitur implisit dari kerangka kerja. Kompilasi runtime melengkapi kompilasi build-time tampilan. Ini memungkinkan kerangka kerja untuk mengkompilasi Razor tampilan dan halaman (.cshtml
file) ketika file dimodifikasi, tanpa harus membangun kembali seluruh aplikasi. Fitur ini mendukung skenario membuat pengeditan cepat di IDE dan menyegarkan browser untuk melihat perubahan.
Dalam ASP.NET Core 3.0, kompilasi runtime adalah skenario keikutsertaan. Kompilasi build-time adalah satu-satunya mekanisme untuk melihat kompilasi yang diaktifkan secara default. Runtime bergantung pada Visual Studio atau dotnet-watch di Visual Studio Code untuk membangun kembali proyek saat mendeteksi perubahan .cshtml
pada file. Di Visual Studio, ubah ke .cs
, .cshtml
, atau .razor
file dalam proyek yang dijalankan (Ctrl+F5), tetapi tidak di-debug (F5), picu kompilasi ulang proyek.
Untuk mengaktifkan kompilasi runtime di proyek ASP.NET Core 3.0 Anda:
Instal Microsoft.AspNetCore.Mvc.Razor. Paket RuntimeCompilation NuGet.
Perbarui
Startup.ConfigureServices
untuk memanggilAddRazorRuntimeCompilation
:Untuk ASP.NET Core MVC, gunakan kode berikut:
services.AddControllersWithViews() .AddRazorRuntimeCompilation(...);
Untuk ASP.NET Core Razor Pages, gunakan kode berikut:
services.AddRazorPages() .AddRazorRuntimeCompilation(...);
Sampel di https://github.com/aspnet/samples/tree/main/samples/aspnetcore/mvc/runtimecompilation menunjukkan contoh mengaktifkan kompilasi runtime secara kondisional di lingkungan Pengembangan.
Untuk informasi selengkapnya tentang Razor kompilasi file, lihat Razor kompilasi file di ASP.NET Core.
Memigrasikan pustaka melalui multi-penargetan
Pustaka sering kali perlu mendukung beberapa versi ASP.NET Core. Sebagian besar pustaka yang dikompilasi terhadap versi ASP.NET Core sebelumnya harus terus berfungsi tanpa masalah. Kondisi berikut mengharuskan aplikasi dikompilasi silang:
- Pustaka bergantung pada fitur yang memiliki perubahan pemecahan biner.
- Pustaka ingin memanfaatkan fitur baru di ASP.NET Core 3.0.
Contohnya:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>netcoreapp3.0;netstandard2.0</TargetFrameworks>
</PropertyGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.0'">
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
<PackageReference Include="Microsoft.AspNetCore" Version="2.1.0" />
</ItemGroup>
</Project>
Gunakan #ifdefs
untuk mengaktifkan API khusus ASP.NET Core 3.0:
var webRootFileProvider =
#if NETCOREAPP3_0
GetRequiredService<IWebHostEnvironment>().WebRootFileProvider;
#elif NETSTANDARD2_0
GetRequiredService<IHostingEnvironment>().WebRootFileProvider;
#else
#error unknown target framework
#endif
Untuk informasi selengkapnya tentang menggunakan API ASP.NET Core di pustaka kelas, lihat Menggunakan API inti ASP.NET di pustaka kelas.
Perubahan lain-lain
Sistem validasi di .NET Core 3.0 dan yang lebih baru memperlakukan parameter yang tidak dapat diubah ke null atau properti terikat seolah-olah mereka memiliki [Required]
atribut. Untuk informasi selengkapnya, lihat atribut [Wajib] .
Terbitkan
Hapus folder bin dan obj di direktori proyek.
TestServer
Untuk aplikasi yang menggunakan TestServer langsung dengan Host Generik, buat TestServer
di IWebHostBuilder di ConfigureWebHost:
[Fact]
public async Task GenericCreateAndStartHost_GetTestServer()
{
using var host = await new HostBuilder()
.ConfigureWebHost(webBuilder =>
{
webBuilder
.UseTestServer()
.Configure(app => { });
})
.StartAsync();
var response = await host.GetTestServer().CreateClient().GetAsync("/");
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}
Perubahan BREAKING API
Tinjau perubahan yang melanggar:
- Daftar lengkap perubahan yang melanggar dalam rilis ASP.NET Core 3.0
- Perubahan API yang melanggar dalam Antiforgery, CORS, Diagnostik, MVC, dan Perutean. Daftar ini mencakup perubahan yang melanggar untuk sakelar kompatibilitas.
- Untuk ringkasan perubahan pemecahan 2.2-ke-3.0 di seluruh .NET Core, ASP.NET Core, dan Entity Framework Core, lihat Melanggar perubahan untuk migrasi dari versi 2.2 ke 3.0.
Perutean titik akhir dengan parameter catch-all
Peringatan
Parameter catch-all mungkin salah mencocokkan rute karena bug dalam perutean. Aplikasi yang terpengaruh oleh bug ini memiliki karakteristik berikut:
- Rute catch-all, misalnya,
{**slug}"
- Rute catch-all gagal mencocokkan permintaan yang harus cocok.
- Menghapus rute lain membuat rute catch-all mulai berfungsi.
Lihat bug GitHub 18677 dan 16579 misalnya kasus yang mengenai bug ini.
Perbaikan keikutsertaan untuk bug ini terkandung dalam .NET Core 3.1.301 SDK dan yang lebih baru. Kode berikut menetapkan sakelar internal yang memperbaiki bug ini:
public static void Main(string[] args)
{
AppContext.SetSwitch("Microsoft.AspNetCore.Routing.UseCorrectCatchAllBehavior",
true);
CreateHostBuilder(args).Build().Run();
}
// Remaining code removed for brevity.
.NET Core 3.0 di Azure App Service
Peluncuran .NET Core ke Azure App Service selesai. .NET Core 3.0 tersedia di semua pusat data Azure App Service.
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.
ASP.NET Core