Menghosting dan menyebarkan ASP.NET Core Blazor WebAssembly
Catatan
Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Peringatan
Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Penting
Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.
Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.
Artikel ini menjelaskan cara menghosting dan menyebarkan Blazor WebAssembly menggunakan ASP.NET Core, Content Delivery Networks (CDN), server file, dan Halaman GitHub.
Blazor WebAssembly Dengan model hosting:
- Aplikasi Blazor , dependensinya, dan runtime .NET diunduh ke browser secara paralel.
- Aplikasi ini dijalankan langsung di utas UI browser.
Artikel ini berkaitan dengan skenario penyebaran tempat Blazor aplikasi ditempatkan di server web atau layanan hosting statis, .NET tidak digunakan untuk melayani Blazor aplikasi. Strategi ini tercakup dalam bagian Penyebaran Mandiri, yang mencakup informasi tentang menghosting Blazor WebAssembly aplikasi sebagai sub-aplikasi IIS.
Strategi penyebaran berikut didukung:
- Aplikasi Blazor ini dilayani oleh aplikasi ASP.NET Core. Strategi ini tercakup dalam bagian Penyebaran yang dihosting dengan ASP.NET Core .
- Aplikasi Blazor ini ditempatkan di server atau layanan web hosting statis, di mana .NET tidak digunakan untuk melayani Blazor aplikasi. Strategi ini tercakup dalam bagian Penyebaran Mandiri, yang mencakup informasi tentang menghosting Blazor WebAssembly aplikasi sebagai sub-aplikasi IIS.
- Aplikasi ASP.NET Core menghosting beberapa Blazor WebAssembly aplikasi. Untuk informasi selengkapnya, lihat Beberapa aplikasi ASP.NET Core Blazor WebAssembly yang dihosting.
Hosting subdomain dan sub-aplikasi IIS
Hosting subdomain tidak memerlukan konfigurasi khusus aplikasi. Anda tidak perlu mengonfigurasi jalur dasar aplikasi ( <base>
tag di wwwroot/index.html
) untuk menghosting aplikasi di subdomain.
Hosting sub-aplikasi IIS memang mengharuskan Anda untuk mengatur jalur dasar aplikasi. Untuk informasi selengkapnya dan tautan silang untuk panduan lebih lanjut tentang hosting sub-aplikasi IIS, lihat Host dan sebarkan ASP.NET Core Blazor.
Mengurangi ukuran timbunan maksimum untuk beberapa browser perangkat seluler
Saat membangun Blazor aplikasi yang berjalan pada klien (.Client
proyek Blazor Web App aplikasi atau aplikasi mandiri Blazor WebAssembly ) dan menargetkan browser perangkat seluler, terutama Safari di iOS, mengurangi memori maksimum untuk aplikasi dengan properti EmccMaximumHeapSize
MSBuild mungkin diperlukan. Nilai defaultnya adalah 2.147.483.648 byte, yang mungkin terlalu besar dan mengakibatkan aplikasi mengalami crash jika aplikasi mencoba mengalokasikan lebih banyak memori dengan browser gagal memberikannya. Contoh berikut menetapkan nilai menjadi 268.435.456 byte dalam Program
file:
Saat membuat Blazor WebAssembly aplikasi yang menargetkan browser perangkat seluler, terutama Safari di iOS, mengurangi memori maksimum untuk aplikasi dengan properti EmccMaximumHeapSize
MSBuild mungkin diperlukan. Nilai defaultnya adalah 2.147.483.648 byte, yang mungkin terlalu besar dan mengakibatkan aplikasi mengalami crash jika aplikasi mencoba mengalokasikan lebih banyak memori dengan browser gagal memberikannya. Contoh berikut menetapkan nilai menjadi 268.435.456 byte dalam Program
file:
<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>
Untuk informasi selengkapnya tentang properti dan target MSBuild Mono/WebAssembly, lihat WasmApp.Common.targets
(dotnet/runtime
repositori GitHub).
Format kemasan webcil untuk rakitan .NET
Webcil adalah format pengemasan yang ramah web untuk rakitan .NET yang dirancang untuk mengaktifkan penggunaan Blazor WebAssembly di lingkungan jaringan terbatas. File webcil menggunakan pembungkus WebAssembly standar, di mana rakitan disebarkan sebagai file WebAssembly yang menggunakan ekstensi file standar .wasm
.
Webcil adalah format kemasan default saat Anda menerbitkan Blazor WebAssembly aplikasi. Untuk menonaktifkan penggunaan Webcil, atur properti MSBuild berikut dalam file proyek aplikasi:
<PropertyGroup>
<WasmEnableWebcil>false</WasmEnableWebcil>
</PropertyGroup>
Menyesuaikan cara sumber daya boot dimuat
Sesuaikan cara sumber daya boot dimuat menggunakan loadBootResource
API. Untuk informasi selengkapnya, lihat startup ASP.NET CoreBlazor.
Kompresi
Blazor WebAssembly Saat aplikasi diterbitkan, output dikompresi secara statis selama penerbitan untuk mengurangi ukuran aplikasi dan menghapus overhead untuk kompresi runtime. Algoritma kompresi berikut digunakan:
Blazor bergantung pada host untuk melayani file terkompresi yang sesuai. Saat menghosting Blazor WebAssembly aplikasi mandiri, pekerjaan tambahan mungkin diperlukan untuk memastikan bahwa file yang dikompresi secara statis disajikan:
Blazor bergantung pada host untuk melayani file terkompresi yang sesuai. Saat menggunakan proyek ASP.NET Core HostedBlazor WebAssembly , proyek host mampu melakukan negosiasi konten dan melayani file yang dikompresi secara statis. Saat menghosting Blazor WebAssembly aplikasi mandiri, pekerjaan tambahan mungkin diperlukan untuk memastikan bahwa file yang dikompresi secara statis disajikan:
- Untuk konfigurasi kompresi IIS
web.config
, lihat bagian kompresi IIS: Brotli dan Gzip. - Saat menghosting solusi hosting statis yang tidak mendukung negosiasi konten file yang dikompresi secara statis, pertimbangkan untuk mengonfigurasi aplikasi untuk mengambil dan mendekode file terkompresi Brotli:
Dapatkan dekoder JavaScript Brotli dari google/brotli
repositori GitHub. File dekoder yang dikurangi diberi nama decode.min.js
dan ditemukan di folder repositorijs
.
Catatan
Jika versi skrip yang dikurangi decode.js
(decode.min.js
) gagal, coba gunakan versi yang tidak dikurangi (decode.js
) sebagai gantinya.
Perbarui aplikasi untuk menggunakan dekoder.
wwwroot/index.html
Dalam file, atur autostart
ke false
pada Blazor<script>
tag:
<script src="_framework/blazor.webassembly.js" autostart="false"></script>
<script>
Setelah Blazortag dan sebelum tag penutup</body>
, tambahkan blok kode <script>
JavaScript berikut.
Blazor Web App:
<script type="module">
import { BrotliDecode } from './decode.min.js';
Blazor.start({
webAssembly: {
loadBootResource: function (type, name, defaultUri, integrity) {
if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration' && type !== 'manifest') {
return (async function () {
const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
if (!response.ok) {
throw new Error(response.statusText);
}
const originalResponseBuffer = await response.arrayBuffer();
const originalResponseArray = new Int8Array(originalResponseBuffer);
const decompressedResponseArray = BrotliDecode(originalResponseArray);
const contentType = type ===
'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
return new Response(decompressedResponseArray,
{ headers: { 'content-type': contentType } });
})();
}
}
}
});
</script>
Mandiri Blazor WebAssembly:
<script type="module">
import { BrotliDecode } from './decode.min.js';
Blazor.start({
loadBootResource: function (type, name, defaultUri, integrity) {
if (type !== 'dotnetjs' && location.hostname !== 'localhost' && type !== 'configuration') {
return (async function () {
const response = await fetch(defaultUri + '.br', { cache: 'no-cache' });
if (!response.ok) {
throw new Error(response.statusText);
}
const originalResponseBuffer = await response.arrayBuffer();
const originalResponseArray = new Int8Array(originalResponseBuffer);
const decompressedResponseArray = BrotliDecode(originalResponseArray);
const contentType = type ===
'dotnetwasm' ? 'application/wasm' : 'application/octet-stream';
return new Response(decompressedResponseArray,
{ headers: { 'content-type': contentType } });
})();
}
}
});
</script>
Untuk informasi selengkapnya tentang memuat sumber daya boot, lihat startup ASP.NET CoreBlazor.
Untuk menonaktifkan pemadatan, tambahkan CompressionEnabled
properti MSBuild ke file proyek aplikasi dan atur nilainya ke false
:
<PropertyGroup>
<CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>
Properti CompressionEnabled
dapat diteruskan ke dotnet publish
perintah dengan sintaks berikut dalam shell perintah:
dotnet publish -p:CompressionEnabled=false
Untuk menonaktifkan pemadatan, tambahkan BlazorEnableCompression
properti MSBuild ke file proyek aplikasi dan atur nilainya ke false
:
<PropertyGroup>
<BlazorEnableCompression>false</BlazorEnableCompression>
</PropertyGroup>
Properti BlazorEnableCompression
dapat diteruskan ke dotnet publish
perintah dengan sintaks berikut dalam shell perintah:
dotnet publish -p:BlazorEnableCompression=false
Menulis ulang URL untuk perutean yang benar
Permintaan perutean untuk komponen halaman dalam Blazor WebAssembly aplikasi tidak sesingkat permintaan perutean di aplikasi Blazor Server . Pertimbangkan aplikasi Blazor WebAssembly dengan dua komponen:
Main.razor
: Memuat di akar aplikasi dan berisi tautan keAbout
komponen (href="About"
).About.razor
:About
komponen.
Saat dokumen default aplikasi diminta menggunakan bilah alamat browser (misalnya, https://www.contoso.com/
):
- Browser membuat permintaan.
- Halaman default dikembalikan, yang biasanya
index.html
. index.html
bootstrap aplikasi.- Router komponen dimuat, dan Razor
Main
komponen dirender.
Di halaman Utama, memilih tautan ke About
komponen berfungsi pada klien karena Blazor router menghentikan browser membuat permintaan di Internet untuk www.contoso.com
About
dan melayani komponen yang dirender About
itu sendiri. Semua permintaan untuk titik akhir internal dalam Blazor WebAssembly aplikasi berfungsi dengan cara yang sama: Permintaan tidak memicu permintaan berbasis browser ke sumber daya yang dihosting server di Internet. Router menangani permintaan secara internal.
Jika permintaan dibuat menggunakan bilah alamat browser untuk www.contoso.com/About
, permintaan gagal. Tidak ada sumber daya seperti itu di host Internet aplikasi, sehingga respons 404 - Tidak Ditemukan dikembalikan.
Karena browser membuat permintaan ke host berbasis Internet untuk halaman sisi klien, server web dan layanan hosting harus menulis ulang semua permintaan untuk sumber daya yang tidak secara fisik di server ke index.html
halaman. Ketika index.html
dikembalikan, router aplikasi Blazor mengambil alih dan merespons dengan sumber daya yang benar.
Saat menyebarkan ke server IIS, Anda dapat menggunakan Modul Penulisan Ulang URL dengan file yang diterbitkan web.config
aplikasi. Untuk informasi selengkapnya, lihat bagian IIS .
Penyebaran yang dihosting dengan ASP.NET Core
Penyebaran yang dihosting melayani Blazor WebAssembly aplikasi ke browser dari aplikasi ASP.NET Core yang berjalan di server web.
Aplikasi klien Blazor WebAssembly diterbitkan ke /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot
dalam folder aplikasi server, bersama dengan aset web statis lainnya dari aplikasi server. Dua aplikasi disebarkan bersama-sama. Server web yang mampu menghosting aplikasi ASP.NET Core diperlukan. Untuk penyebaran yang dihosting, Visual Studio menyertakan Blazor WebAssembly templat Proyek aplikasi (blazorwasm
templat saat menggunakan dotnet new
perintah) dengan Hosted
opsi dipilih (-ho|--hosted
saat menggunakan dotnet new
perintah ).
Untuk informasi lebih lanjut, baca artikel berikut:
- ASP.NET Hosting dan penyebaran aplikasi Core: Host dan sebarkan ASP.NET Core
- Penyebaran ke Azure App Service: Menerbitkan aplikasi ASP.NET Core ke Azure dengan Visual Studio
- Blazortemplat proyek: struktur proyek ASP.NET Core Blazor
Penyebaran yang dihosting dari executable yang bergantung pada kerangka kerja untuk platform tertentu
Untuk menyebarkan aplikasi yang dihosting Blazor WebAssembly sebagai executable yang bergantung pada kerangka kerja untuk platform tertentu (tidak mandiri) gunakan panduan berikut berdasarkan alat yang digunakan.
Visual Studio
Penyebaran mandiri dikonfigurasi untuk profil penerbitan yang dihasilkan (.pubxml
). Konfirmasikan bahwa profil penerbitan Server proyek berisi <SelfContained>
properti MSBuild yang diatur ke false
.
.pubxml
Dalam file profil publikasi di Server folder proyekProperties
:
<SelfContained>false</SelfContained>
Atur Pengidentifikasi Runtime (RID) menggunakan pengaturan Runtime Target di area Pengaturan UI Terbitkan, yang menghasilkan <RuntimeIdentifier>
properti MSBuild di profil penerbitan:
<RuntimeIdentifier>{RID}</RuntimeIdentifier>
Dalam konfigurasi sebelumnya, {RID}
tempat penampung adalah Pengidentifikasi Runtime (RID).
Terbitkan Server proyek dalam konfigurasi Rilis .
Catatan
Dimungkinkan untuk menerbitkan aplikasi dengan menerbitkan pengaturan profil menggunakan .NET CLI dengan meneruskan /p:PublishProfile={PROFILE}
ke dotnet publish
perintah, di mana {PROFILE}
tempat penampung adalah profil. Untuk informasi selengkapnya, lihat bagian Terbitkan profil dan Contoh penerbitan folder di artikel penerbitan profil penerbitan Visual Studio (.pubxml) untuk penyebaran aplikasi ASP.NET Core. Jika Anda meneruskan RID dalam dotnet publish
perintah dan bukan di profil penerbitan, gunakan properti MSBuild (/p:RuntimeIdentifier
) dengan perintah , bukan dengan -r|--runtime
opsi .
.NET CLI
Konfigurasikan penyebaran mandiri dengan menempatkan <SelfContained>
properti MSBuild dalam file Server proyek yang <PropertyGroup>
diatur ke false
:
<SelfContained>false</SelfContained>
Penting
Properti SelfContained
harus ditempatkan dalam Server file proyek. Properti tidak dapat diatur dengan benar dengan dotnet publish
perintah menggunakan --no-self-contained
opsi atau properti /p:SelfContained=false
MSBuild .
Atur Pengidentifikasi Runtime (RID) menggunakan salah satu pendekatan berikut:
Opsi 1: Atur RID dalam
<PropertyGroup>
dalam Server file proyek proyek:<RuntimeIdentifier>{RID}</RuntimeIdentifier>
Dalam konfigurasi sebelumnya,
{RID}
tempat penampung adalah Pengidentifikasi Runtime (RID).Terbitkan aplikasi dalam konfigurasi Rilis dari Server proyek:
dotnet publish -c Release
Opsi 2: Teruskan RID dalam
dotnet publish
perintah sebagai properti MSBuild (/p:RuntimeIdentifier
), bukan dengan-r|--runtime
opsi:dotnet publish -c Release /p:RuntimeIdentifier={RID}
Dalam perintah sebelumnya,
{RID}
tempat penampung adalah Pengidentifikasi Runtime (RID).
Untuk informasi lebih lanjut, baca artikel berikut:
Penyebaran yang dihosting dengan beberapa Blazor WebAssembly aplikasi
Untuk informasi selengkapnya, lihat Beberapa aplikasi ASP.NET Core Blazor WebAssembly yang dihosting.
Penyebaran mandiri
Penyebaran mandiri melayani Blazor WebAssembly aplikasi sebagai sekumpulan file statis yang diminta langsung oleh klien. Server file statis apa pun dapat melayani Blazor aplikasi.
Aset penyebaran mandiri diterbitkan ke dalam /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot
folder atau bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\
(tergantung pada versi .NET SDK yang digunakan), di mana {TARGET FRAMEWORK}
tempat penampung adalah kerangka kerja target.
Azure App Service
Blazor WebAssembly aplikasi dapat disebarkan ke Azure App Services di Windows, yang menghosting aplikasi di IIS.
Menyebarkan aplikasi mandiri Blazor WebAssembly ke Azure App Service untuk Linux saat ini tidak didukung. Sebaiknya hosting aplikasi mandiri Blazor WebAssembly menggunakan Azure Static Web Apps, yang mendukung skenario ini.
Azure Static Web Apps
Gunakan salah satu pendekatan berikut untuk menyebarkan Blazor WebAssembly aplikasi ke Azure Static Web Apps:
Sebarkan dari Visual Studio
Untuk menyebarkan dari Visual Studio, buat profil penerbitan untuk Azure Static Web Apps:
Simpan pekerjaan yang belum disimpan dalam proyek, karena mulai ulang Visual Studio mungkin diperlukan selama proses.
Di UI Terbitkan Visual Studio, pilih Target>Azure>Specific Target>Azure Static Web Apps untuk membuat profil penerbitan.
Jika komponen Alat Azure WebJobs untuk Visual Studio tidak diinstal, perintah akan muncul untuk menginstal komponen ASP.NET dan pengembangan web. Ikuti perintah untuk menginstal alat menggunakan Alat Penginstal Visual Studio. Visual Studio menutup dan membuka kembali secara otomatis saat menginstal alat. Setelah alat diinstal, mulai kembali pada langkah pertama untuk membuat profil penerbitan.
Dalam konfigurasi profil publikasi, berikan nama Langganan. Pilih instans yang sudah ada, atau pilih Buat instans baru. Saat membuat instans baru di UI Buat Aplikasi Web Statis portal Azure, atur Sumber detail>penyebaran ke Lainnya. Tunggu hingga penyebaran selesai di portal Azure sebelum melanjutkan.
Dalam konfigurasi profil penerbitan, pilih instans Azure Static Web Apps dari grup sumber daya instans. Pilih Selesai untuk membuat profil penerbitan. Jika Visual Studio meminta untuk menginstal CLI Static Web Apps (SWA), instal CLI dengan mengikuti perintah. SWA CLI memerlukan NPM/Node.js (dokumentasi Visual Studio).
Setelah profil publikasi dibuat, sebarkan aplikasi ke instans Azure Static Web Apps menggunakan profil terbitkan dengan memilih tombol Terbitkan .
Menyebarkan dari Visual Studio Code
Untuk menyebarkan dari Visual Studio Code, lihat Mulai Cepat: Membangun situs statis pertama Anda dengan Azure Static Web Apps.
Sebarkan dari GitHub
Untuk menyebarkan dari repositori GitHub, lihat Tutorial: Membangun aplikasi web statis dengan Blazor di Azure Static Web Apps.
IIS
IIS adalah server file statis yang mampu untuk Blazor aplikasi. Untuk mengonfigurasi IIS untuk menghosting Blazor, lihat Membangun Situs Web Statis di IIS.
Aset yang diterbitkan dibuat di /bin/Release/{TARGET FRAMEWORK}/publish
folder atau bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish
, tergantung pada versi SDK mana yang digunakan dan di mana {TARGET FRAMEWORK}
tempat penampung adalah kerangka kerja target. Host konten publish
folder di server web atau layanan hosting.
web.config
Blazor Saat proyek diterbitkan, web.config
file dibuat dengan konfigurasi IIS berikut:
- Jenis MIME
- Pemadatan HTTP diaktifkan untuk jenis MIME berikut:
application/octet-stream
application/wasm
- Aturan Modul Penulisan Ulang URL dibuat:
- Layani sub-direktori tempat aset statis aplikasi berada (
wwwroot/{PATH REQUESTED}
). - Buat perutean fallback SPA sehingga permintaan untuk aset non-file dialihkan ke dokumen default aplikasi di folder aset statisnya (
wwwroot/index.html
).
- Layani sub-direktori tempat aset statis aplikasi berada (
Menggunakan kustom web.config
Untuk menggunakan file kustom web.config
:
- Tempatkan file kustom
web.config
di folder akar proyek. - Terbitkan proyek. Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.
- Tempatkan file kustom
web.config
di folder akar proyek. Untuk solusi yang dihosting, tempatkan Blazor WebAssemblyfile di Server folder proyek. - Terbitkan proyek. Untuk solusi yang dihosting, terbitkan Blazor WebAssembly solusi dari Server proyek. Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.
Jika pembuatan atau transformasi SDK web.config
selama penerbitan tidak memindahkan file ke aset yang diterbitkan di publish
folder atau memodifikasi konfigurasi kustom dalam file kustom web.config
Anda, gunakan salah satu pendekatan berikut sesuai kebutuhan untuk mengambil kontrol penuh atas proses:
Jika SDK tidak menghasilkan file, misalnya, dalam aplikasi mandiri di atau , tergantung pada versi SDK mana yang digunakan dan di mana
{TARGET FRAMEWORK}
tempat penampung adalah kerangka kerja target, atur<PublishIISAssets>
properti ketrue
dalam file proyek (.csproj
).bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish
/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot
Blazor WebAssembly Biasanya untuk aplikasi WebAssembly mandiri, ini adalah satu-satunya pengaturan yang diperlukan untuk memindahkan file kustomweb.config
dan mencegah transformasi file oleh SDK.<PropertyGroup> <PublishIISAssets>true</PublishIISAssets> </PropertyGroup>
Nonaktifkan transformasi SDK
web.config
dalam file proyek (.csproj
):<PropertyGroup> <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled> </PropertyGroup>
Tambahkan target kustom ke file proyek (
.csproj
) untuk memindahkan file kustomweb.config
. Dalam contoh berikut, file kustomweb.config
ditempatkan oleh pengembang di akar proyek.web.config
Jika file berada di tempat lain, tentukan jalur ke file diSourceFiles
. Contoh berikut menentukanpublish
folder dengan$(PublishDir)
, tetapi menyediakan jalur keDestinationFolder
untuk lokasi output kustom.<Target Name="CopyWebConfig" AfterTargets="Publish"> <Copy SourceFiles="web.config" DestinationFolder="$(PublishDir)" /> </Target>
Menginstal Modul Penulisan Ulang URL
Modul Penulisan Ulang URL diperlukan untuk menulis ulang URL. Modul tidak diinstal secara default, dan tidak tersedia untuk diinstal sebagai fitur layanan peran Server Web (IIS). Modul harus diunduh dari situs web IIS. Gunakan Penginstal Platform Web untuk menginstal modul:
- Secara lokal, navigasikan ke halaman unduhan Modul Penulisan Ulang URL. Untuk versi bahasa Inggris, pilih WebPI untuk mengunduh penginstal WebPI. Untuk bahasa lain, pilih arsitektur yang sesuai untuk server (x86/x64) untuk mengunduh alat penginstal.
- Salin alat penginstal ke server. Jalankan alat penginstal. Pilih tombol Instal dan terima ketentuan lisensi. Menghidupkan ulang server tidak diperlukan setelah penginstalan selesai.
Mengonfigurasi situs web
Atur jalur Fisik situs web ke folder aplikasi. Folder berisi:
- File
web.config
yang digunakan IIS untuk mengonfigurasi situs web, termasuk aturan pengalihan dan jenis konten file yang diperlukan. - Folder aset statis aplikasi.
Host sebagai sub-aplikasi IIS
Jika aplikasi mandiri dihosting sebagai sub-aplikasi IIS, lakukan salah satu hal berikut:
Nonaktifkan handler Modul inti ASP.NET yang diwariskan.
Hapus handler di Blazor file yang diterbitkan
web.config
aplikasi dengan menambahkan<handlers>
bagian ke bagian<system.webServer>
file:<handlers> <remove name="aspNetCore" /> </handlers>
Nonaktifkan pewarisan bagian aplikasi
<system.webServer>
root (induk) menggunakan<location>
elemen denganinheritInChildApplications
diatur kefalse
:<?xml version="1.0" encoding="utf-8"?> <configuration> <location path="." inheritInChildApplications="false"> <system.webServer> <handlers> <add name="aspNetCore" ... /> </handlers> <aspNetCore ... /> </system.webServer> </location> </configuration>
Catatan
Menonaktifkan pewarisan bagian aplikasi
<system.webServer>
root (induk) adalah konfigurasi default untuk aplikasi yang diterbitkan menggunakan .NET SDK.
Menghapus handler atau menonaktifkan pewarisan dilakukan selain mengonfigurasi jalur dasar aplikasi. Atur jalur dasar aplikasi dalam file aplikasi index.html
ke alias IIS yang digunakan saat mengonfigurasi sub-aplikasi di IIS.
Konfigurasikan jalur dasar aplikasi dengan mengikuti panduan di artikel Host dan sebarkan ASP.NET Core Blazor .
Kompresi Brotli dan Gzip
Bagian ini hanya berlaku untuk aplikasi mandiri Blazor WebAssembly .
Bagian ini hanya berlaku untuk aplikasi mandiri Blazor WebAssembly . Aplikasi yang dihosting Blazor menggunakan file aplikasi web.config
ASP.NET Core default, bukan file yang ditautkan di bagian ini.
IIS dapat dikonfigurasi melalui web.config
untuk melayani aset terkompresi Blazor Brotli atau Gzip untuk aplikasi mandiri Blazor WebAssembly . Untuk contoh file konfigurasi, lihat web.config
.
Konfigurasi tambahan file contoh web.config
mungkin diperlukan dalam skenario berikut:
- Spesifikasi aplikasi memanggil salah satu hal berikut:
- Menyajikan file terkompresi yang tidak dikonfigurasi oleh file contoh
web.config
. - Menyajikan file terkompresi yang dikonfigurasi oleh file contoh
web.config
dalam format yang tidak dikompresi.
- Menyajikan file terkompresi yang tidak dikonfigurasi oleh file contoh
- Konfigurasi IIS server (misalnya,
applicationHost.config
) menyediakan default IIS tingkat server. Bergantung pada konfigurasi tingkat server, aplikasi mungkin memerlukan konfigurasi IIS yang berbeda dari apa yang dikandung file contohweb.config
.
Untuk informasi selengkapnya tentang file kustom web.config
, lihat bagian Menggunakan kustom web.config
.
Pemecahan Masalah
Jika 500 - Kesalahan Server Internal diterima dan Manajer IIS melemparkan kesalahan saat mencoba mengakses konfigurasi situs web, konfirmasikan bahwa Modul Penulisan Ulang URL diinstal. Saat modul tidak diinstal, web.config
file tidak dapat diurai oleh IIS. Ini mencegah Manajer IIS memuat konfigurasi situs web dan situs web dari menyajikan Blazorfile statis.
Untuk informasi selengkapnya tentang pemecahan masalah penyebaran ke IIS, lihat Memecahkan masalah ASP.NET Core di Azure App Service dan IIS.
Azure Storage
Hosting file statis Azure Storage memungkinkan hosting aplikasi tanpa Blazor server. Nama domain kustom, Azure Content Delivery Network (CDN), dan HTTPS didukung.
Ketika layanan blob diaktifkan untuk hosting situs web statis di akun penyimpanan:
- Atur nama dokumen Indeks ke
index.html
. - Atur jalur dokumen Kesalahan ke
index.html
. Razor komponen dan titik akhir non-file lainnya tidak berada di jalur fisik dalam konten statis yang disimpan oleh layanan blob. Ketika permintaan untuk salah satu sumber daya ini diterima yang harus ditangani Blazor router, kesalahan 404 - Tidak Ditemukan yang dihasilkan oleh layanan blob merutekan permintaan ke jalur dokumen Kesalahan.index.html
Blob dikembalikan, dan Blazor router memuat dan memproses jalur.
Jika file tidak dimuat pada runtime karena jenis MIME yang tidak pantas di header file Content-Type
, ambil salah satu tindakan berikut:
Konfigurasikan alat Anda untuk mengatur jenis MIME (
Content-Type
header) yang benar saat file disebarkan.Ubah jenis MIME (
Content-Type
header) untuk file setelah aplikasi disebarkan.Di Storage Explorer (portal Azure) untuk setiap file:
- Klik kanan file dan pilih Properti.
- Atur ContentType dan pilih tombol Simpan .
Untuk informasi selengkapnya, lihat Hosting situs web statik di Azure Storage.
Nginx.
File berikut disederhanakan nginx.conf
untuk menunjukkan cara mengonfigurasi Nginx untuk mengirim index.html
file setiap kali tidak dapat menemukan file yang sesuai pada disk.
events { }
http {
server {
listen 80;
location / {
root /usr/share/nginx/html;
try_files $uri $uri/ /index.html =404;
}
}
}
Saat mengatur batas laju ledakan NGINX dengan limit_req
, Blazor WebAssembly aplikasi mungkin memerlukan nilai parameter besar burst
untuk mengakomodasi jumlah permintaan yang relatif besar yang dibuat oleh aplikasi. Awalnya, atur nilai ke setidaknya 60:
http {
server {
...
location / {
...
limit_req zone=one burst=60 nodelay;
}
}
}
Tingkatkan nilai jika alat pengembang browser atau alat lalu lintas jaringan menunjukkan bahwa permintaan menerima kode status 503 - Layanan Tidak Tersedia .
Untuk informasi selengkapnya tentang konfigurasi server web Nginx produksi, lihat Membuat File Konfigurasi NGINX Plus dan NGINX.
Apache
Untuk menyebarkan Blazor WebAssembly aplikasi ke Apache:
Buat file konfigurasi Apache. Contoh berikut adalah file konfigurasi yang disederhanakan (
blazorapp.config
):<VirtualHost *:80> ServerName www.example.com ServerAlias *.example.com DocumentRoot "/var/www/blazorapp" ErrorDocument 404 /index.html AddType application/wasm .wasm <Directory "/var/www/blazorapp"> Options -Indexes AllowOverride None </Directory> <IfModule mod_deflate.c> AddOutputFilterByType DEFLATE text/css AddOutputFilterByType DEFLATE application/javascript AddOutputFilterByType DEFLATE text/html AddOutputFilterByType DEFLATE application/octet-stream AddOutputFilterByType DEFLATE application/wasm <IfModule mod_setenvif.c> BrowserMatch ^Mozilla/4 gzip-only-text/html BrowserMatch ^Mozilla/4.0[678] no-gzip BrowserMatch bMSIE !no-gzip !gzip-only-text/html </IfModule> </IfModule> ErrorLog /var/log/httpd/blazorapp-error.log CustomLog /var/log/httpd/blazorapp-access.log common </VirtualHost>
Buat file konfigurasi Apache. Contoh berikut adalah file konfigurasi yang disederhanakan (
blazorapp.config
):<VirtualHost *:80> ServerName www.example.com ServerAlias *.example.com DocumentRoot "/var/www/blazorapp" ErrorDocument 404 /index.html AddType application/wasm .wasm AddType application/octet-stream .dll <Directory "/var/www/blazorapp"> Options -Indexes AllowOverride None </Directory> <IfModule mod_deflate.c> AddOutputFilterByType DEFLATE text/css AddOutputFilterByType DEFLATE application/javascript AddOutputFilterByType DEFLATE text/html AddOutputFilterByType DEFLATE application/octet-stream AddOutputFilterByType DEFLATE application/wasm <IfModule mod_setenvif.c> BrowserMatch ^Mozilla/4 gzip-only-text/html BrowserMatch ^Mozilla/4.0[678] no-gzip BrowserMatch bMSIE !no-gzip !gzip-only-text/html </IfModule> </IfModule> ErrorLog /var/log/httpd/blazorapp-error.log CustomLog /var/log/httpd/blazorapp-access.log common </VirtualHost>
Tempatkan file konfigurasi Apache ke
/etc/httpd/conf.d/
dalam direktori.Tempatkan aset yang diterbitkan aplikasi (
/bin/Release/{TARGET FRAMEWORK}/publish/wwwroot
, di mana{TARGET FRAMEWORK}
tempat penampung adalah kerangka kerja target) ke dalam/var/www/blazorapp
direktori (lokasi yang ditentukanDocumentRoot
dalam file konfigurasi).Mulai ulang layanan Apache.
Untuk informasi lebih lanjut, lihat mod_mime
dan mod_deflate
.
GitHub Pages
Tindakan GitHub default, yang menyebarkan halaman, melewati penyebaran folder yang dimulai dengan garis bawah, misalnya, _framework
folder . Untuk menyebarkan folder yang dimulai dengan garis bawah, tambahkan file kosong .nojekyll
ke cabang Git.
Git memperlakukan file JavaScript (JS), seperti , seperti blazor.webassembly.js
teks dan mengonversi akhir baris dari CRLF (umpan baris kembali pengangkutan) ke LF (umpan baris) dalam alur penyebaran. Perubahan JS pada file ini menghasilkan hash file yang berbeda dari Blazor yang dikirim ke klien dalam blazor.boot.json
file. Ketidakcocokan mengakibatkan kegagalan pemeriksaan integritas pada klien. Salah satu pendekatan untuk memecahkan masalah ini adalah menambahkan .gitattributes
file dengan *.js binary
baris sebelum menambahkan aset aplikasi ke cabang Git. Baris mengonfigurasi *.js binary
Git untuk memperlakukan JS file sebagai file biner, yang menghindari pemrosesan file dalam alur penyebaran. Hash file dari file yang tidak diproses cocok dengan entri dalam blazor.boot.json
file, dan pemeriksaan integritas sisi klien lulus. Untuk informasi selengkapnya, lihat ASP.NET runtime Core Blazor WebAssembly .NET dan penembolokan bundel aplikasi.
Untuk menangani penulisan ulang URL, tambahkan wwwroot/404.html
file dengan skrip yang menangani pengalihan permintaan ke index.html
halaman. Misalnya, lihat SteveSandersonMS/BlazorOnGitHubPages
repositori GitHub:
Saat menggunakan situs proyek alih-alih situs organisasi, perbarui <base>
tag di wwwroot/index.html
. Atur href
nilai atribut ke nama repositori GitHub dengan garis miring berikutnya (misalnya, /my-repository/
). SteveSandersonMS/BlazorOnGitHubPages
Di repositori GitHub, basis href
diperbarui saat diterbitkan oleh .github/workflows/main.yml
file konfigurasi.
Catatan
Repositori SteveSandersonMS/BlazorOnGitHubPages
GitHub tidak dimiliki, dikelola, atau didukung oleh .NET Foundation atau Microsoft.
Mandiri dengan Docker
Aplikasi mandiri Blazor WebAssembly diterbitkan sebagai sekumpulan file statis untuk dihosting oleh server file statis.
Untuk menghosting aplikasi di Docker:
- Pilih kontainer Docker dengan dukungan server web, seperti Ngnix atau Apache.
publish
Salin aset folder ke folder lokasi yang ditentukan di server web untuk melayani file statis.- Terapkan konfigurasi tambahan sesuai kebutuhan untuk melayani Blazor WebAssembly aplikasi.
Untuk panduan konfigurasi, lihat sumber daya berikut:
- Bagian Nginx atau bagian Apache di artikel ini
- Dokumentasi Docker
Nilai konfigurasi host
Blazor WebAssembly aplikasi dapat menerima nilai konfigurasi host berikut sebagai argumen baris perintah saat runtime di lingkungan pengembangan.
Akar konten
Argumen --contentroot
mengatur jalur absolut ke direktori yang berisi file konten aplikasi (akar konten). Dalam contoh berikut, /content-root-path
adalah jalur akar konten aplikasi.
Teruskan argumen saat menjalankan aplikasi secara lokal pada prompt perintah. Dari direktori aplikasi, jalankan:
dotnet watch --contentroot=/content-root-path
Tambahkan entri ke file aplikasi
launchSettings.json
di profil IIS Express . Pengaturan ini digunakan saat aplikasi dijalankan dengan Visual Studio Debugger dan dari prompt perintah dengandotnet watch
(ataudotnet run
)."commandLineArgs": "--contentroot=/content-root-path"
Di Visual Studio, tentukan argumen dalam argumen Aplikasi Debug>Properti.> Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke
launchSettings.json
file.--contentroot=/content-root-path
Basis jalur
Argumen --pathbase
mengatur jalur dasar aplikasi untuk aplikasi yang dijalankan secara lokal dengan jalur URL relatif non-root ( <base>
tag href
diatur ke jalur selain /
untuk penahapan dan produksi). Dalam contoh berikut, /relative-URL-path
adalah basis jalur aplikasi. Untuk informasi selengkapnya, lihat Jalur dasar aplikasi.
Penting
Tidak seperti jalur yang disediakan untuk href
<base>
tag, jangan sertakan garis miring berikutnya (/
) saat meneruskan --pathbase
nilai argumen. Jika jalur dasar aplikasi disediakan dalam <base>
tag sebagai <base href="/CoolApp/">
(menyertakan garis miring berikutnya), berikan nilai argumen baris perintah sebagai --pathbase=/CoolApp
(tidak ada garis miring berikutnya).
Teruskan argumen saat menjalankan aplikasi secara lokal pada prompt perintah. Dari direktori aplikasi, jalankan:
dotnet watch --pathbase=/relative-URL-path
Tambahkan entri ke file aplikasi
launchSettings.json
di profil IIS Express . Pengaturan ini digunakan saat menjalankan aplikasi dengan Visual Studio Debugger dan dari prompt perintah dengandotnet watch
(ataudotnet run
)."commandLineArgs": "--pathbase=/relative-URL-path"
Di Visual Studio, tentukan argumen dalam argumen Aplikasi Debug>Properti.> Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke
launchSettings.json
file.--pathbase=/relative-URL-path
URL
Argumen --urls
mengatur alamat IP atau alamat host dengan port dan protokol untuk mendengarkan permintaan.
Teruskan argumen saat menjalankan aplikasi secara lokal pada prompt perintah. Dari direktori aplikasi, jalankan:
dotnet watch --urls=http://127.0.0.1:0
Tambahkan entri ke file aplikasi
launchSettings.json
di profil IIS Express . Pengaturan ini digunakan saat menjalankan aplikasi dengan Visual Studio Debugger dan dari prompt perintah dengandotnet watch
(ataudotnet run
)."commandLineArgs": "--urls=http://127.0.0.1:0"
Di Visual Studio, tentukan argumen dalam argumen Aplikasi Debug>Properti.> Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke
launchSettings.json
file.--urls=http://127.0.0.1:0
Penyebaran yang dihosting di Linux (Nginx)
Konfigurasikan aplikasi dengan ForwardedHeadersOptions untuk meneruskan X-Forwarded-For
header dan X-Forwarded-Proto
dengan mengikuti panduan di Mengonfigurasi ASP.NET Core untuk bekerja dengan server proksi dan load balancer.
Untuk informasi selengkapnya tentang mengatur jalur dasar aplikasi, termasuk konfigurasi jalur sub-aplikasi, lihat Menghosting dan menyebarkan ASP.NET Core Blazor.
Ikuti panduan untuk aplikasi ASP.NET Core SignalR dengan perubahan berikut:
Hapus konfigurasi untuk buffering proksi (
proxy_buffering off;
) karena pengaturan hanya berlaku untuk Peristiwa Terkirim Server (SSE), yang tidak relevan dengan Blazor interaksi server klien aplikasi.location
Ubah jalur dari/hubroute
(location /hubroute { ... }
) ke jalur/{PATH}
sub-aplikasi (location /{PATH} { ... }
), di mana{PATH}
tempat penampung adalah jalur sub-aplikasi.Contoh berikut mengonfigurasi server untuk aplikasi yang merespons permintaan di jalur
/
akar :http { server { ... location / { ... } } }
Contoh berikut mengonfigurasi jalur sub-aplikasi dari
/blazor
:http { server { ... location /blazor { ... } } }
Untuk informasi selengkapnya dan panduan konfigurasi, lihat sumber daya berikut:
- Menghosting ASP.NET Core di Linux dengan Nginx
- Dokumentasi Nginx:
- Pengembang di forum dukungan non-Microsoft:
Mengonfigurasi Pemangkas
Blazor melakukan pemangkasan Bahasa Perantara (IL) pada setiap build Rilis untuk menghapus IL yang tidak perlu dari rakitan output. Untuk informasi selengkapnya, lihat Mengonfigurasi Pemangkas untuk ASP.NET Core Blazor.
Mengonfigurasi Penaut
Blazor melakukan penautan Bahasa Perantara (IL) pada setiap build Rilis untuk menghapus IL yang tidak perlu dari rakitan output. Untuk informasi selengkapnya, lihat Mengonfigurasi Linker untuk ASP.NET Core Blazor.
Mengubah ekstensi nama file file DLL
Bagian ini berlaku untuk ASP.NET Core 6.x dan 7.x. Dalam ASP.NET Core di .NET 8 atau yang lebih baru, rakitan .NET disebarkan sebagai file WebAssembly (.wasm
) menggunakan format file Webcil. Di ASP.NET Core di .NET 8 atau yang lebih baru, bagian ini hanya berlaku jika format file Webcil telah dinonaktifkan dalam file proyek aplikasi.
Jika firewall, program anti-virus, atau appliance keamanan jaringan memblokir transmisi file pustaka tautan dinamis (DLL) aplikasi (.dll
), Anda dapat mengikuti panduan di bagian ini untuk mengubah ekstensi nama file dari file DLL yang diterbitkan aplikasi.
Catatan
Mengubah ekstensi nama file file DLL aplikasi mungkin tidak menyelesaikan masalah karena banyak sistem keamanan memindai konten file aplikasi, bukan hanya memeriksa ekstensi file.
Untuk pendekatan yang lebih kuat di lingkungan yang memblokir pengunduhan dan eksekusi file DLL, gunakan ASP.NET Core di .NET 8 atau yang lebih baru, yang mengemas rakitan .NET sebagai file WebAssembly (.wasm
) menggunakan format file Webcil . Untuk informasi selengkapnya, lihat bagian Format kemasan Webcil untuk rakitan .NET di versi 8.0 atau yang lebih baru dari artikel ini.
Pendekatan pihak ketiga ada untuk menangani masalah ini. Untuk informasi selengkapnya, lihat sumber daya di Awesome Blazor.
Catatan
Mengubah ekstensi nama file file DLL aplikasi mungkin tidak menyelesaikan masalah karena banyak sistem keamanan memindai konten file aplikasi, bukan hanya memeriksa ekstensi file.
Untuk pendekatan yang lebih kuat di lingkungan yang memblokir pengunduhan dan eksekusi file DLL, lakukan salah satu pendekatan berikut:
- Gunakan ASP.NET Core di .NET 8 atau yang lebih baru, yang mengemas rakitan .NET sebagai file WebAssembly (
.wasm
) menggunakan format file Webcil . Untuk informasi selengkapnya, lihat bagian Format kemasan Webcil untuk rakitan .NET di versi 8.0 atau yang lebih baru dari artikel ini. - Di ASP.NET Core di .NET 6 atau yang lebih baru, gunakan tata letak penyebaran kustom.
Pendekatan pihak ketiga ada untuk menangani masalah ini. Untuk informasi selengkapnya, lihat sumber daya di Awesome Blazor.
Setelah menerbitkan aplikasi, gunakan skrip shell atau alur build DevOps untuk mengganti nama .dll
file untuk menggunakan ekstensi file yang berbeda di direktori output aplikasi yang diterbitkan.
Dalam contoh berikut:
- PowerShell (PS) digunakan untuk memperbarui ekstensi file.
.dll
file diganti namanya untuk menggunakan.bin
ekstensi file dari baris perintah.- File yang tercantum dalam file yang diterbitkan
blazor.boot.json
dengan.dll
ekstensi file diperbarui ke.bin
ekstensi file. - Jika aset pekerja layanan juga digunakan, perintah PowerShell memperbarui file yang
.dll
tercantum dalamservice-worker-assets.js
file ke.bin
ekstensi file.
Untuk menggunakan ekstensi file yang berbeda dari .bin
, ganti .bin
dalam perintah berikut dengan ekstensi file yang diinginkan.
Di Windows:
dir {PATH} | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content {PATH}\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\blazor.boot.json
Dalam perintah sebelumnya, {PATH}
tempat penampung adalah jalur ke folder yang diterbitkan _framework
(misalnya, .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework
dari folder akar proyek).
Jika aset pekerja layanan juga digunakan:
((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js
Dalam perintah sebelumnya, {PATH}
tempat penampung adalah jalur ke file yang diterbitkan service-worker-assets.js
.
Di Linux atau macOS:
for f in {PATH}/*; do mv "$f" "`echo $f | sed -e 's/\.dll/.bin/g'`"; done
sed -i 's/\.dll"/.bin"/g' {PATH}/blazor.boot.json
Dalam perintah sebelumnya, {PATH}
tempat penampung adalah jalur ke folder yang diterbitkan _framework
(misalnya, .\bin\Release\net6.0\browser-wasm\publish\wwwroot\_framework
dari folder akar proyek).
Jika aset pekerja layanan juga digunakan:
sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js
Dalam perintah sebelumnya, {PATH}
tempat penampung adalah jalur ke file yang diterbitkan service-worker-assets.js
.
Untuk mengatasi terkompresi blazor.boot.json.gz
dan blazor.boot.json.br
file, adopsi salah satu pendekatan berikut:
- Hapus file dan
blazor.boot.json.br
terkompresiblazor.boot.json.gz
. Pemadatan dinonaktifkan dengan pendekatan ini. - Rekompresi file yang diperbarui
blazor.boot.json
.
Panduan sebelumnya untuk file terkompresi blazor.boot.json
juga berlaku ketika aset pekerja layanan sedang digunakan. Hapus atau rekompresi service-worker-assets.js.br
dan service-worker-assets.js.gz
. Jika tidak, pemeriksaan integritas file gagal di browser.
Contoh Windows berikut untuk .NET 6 menggunakan skrip PowerShell yang ditempatkan di akar proyek. Skrip berikut, yang menonaktifkan kompresi, adalah dasar untuk modifikasi lebih lanjut jika Anda ingin mengkompresi blazor.boot.json
ulang file.
ChangeDLLExtensions.ps1:
:
param([string]$filepath,[string]$tfm)
dir $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework | rename-item -NewName { $_.name -replace ".dll\b",".bin" }
((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\blazor.boot.json.br
Jika aset pekerja layanan juga digunakan, tambahkan perintah berikut:
((Get-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.gz
Remove-Item $filepath\bin\Release\$tfm\browser-wasm\publish\wwwroot\_framework\wwwroot\service-worker-assets.js.br
Dalam file proyek, skrip dijalankan setelah menerbitkan aplikasi untuk Release
konfigurasi:
<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">
<Exec Command="powershell.exe -command "& { .\ChangeDLLExtensions.ps1 '$(SolutionDir)' '$(TargetFramework)'}"" />
</Target>
Catatan
Saat mengganti nama dan malas memuat rakitan yang sama, lihat panduan dalam rakitan beban Malas di ASP.NET Core Blazor WebAssembly.
Biasanya, server aplikasi memerlukan konfigurasi aset statis untuk melayani file dengan ekstensi yang diperbarui. Untuk aplikasi yang dihosting oleh IIS, tambahkan entri peta MIME (<mimeMap>
) untuk ekstensi file baru di bagian konten statis (<staticContent>
) dalam file kustom web.config
. Contoh berikut mengasumsikan bahwa ekstensi file diubah dari .dll
menjadi .bin
:
<staticContent>
...
<mimeMap fileExtension=".bin" mimeType="application/octet-stream" />
...
</staticContent>
Sertakan pembaruan untuk file terkompresi jika pemadatan sedang digunakan:
<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" />
<mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />
Hapus entri untuk .dll
ekstensi file:
- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />
Hapus entri untuk file terkompresi .dll
jika pemadatan sedang digunakan:
- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />
- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />
Untuk informasi selengkapnya tentang file kustom web.config
, lihat bagian Menggunakan kustom web.config
.
Kerusakan penyebaran sebelumnya
Biasanya pada penyebaran:
- Hanya file yang telah berubah yang diganti, yang biasanya menghasilkan penyebaran yang lebih cepat.
- File yang ada yang bukan bagian dari penyebaran baru dibiarkan untuk digunakan oleh penyebaran baru.
Dalam kasus yang jarang terjadi, file yang berlama-lama dari penyebaran sebelumnya dapat merusak penyebaran baru. Menghapus sepenuhnya penyebaran yang ada (atau aplikasi yang diterbitkan secara lokal sebelum penyebaran) dapat menyelesaikan masalah dengan penyebaran yang rusak. Seringkali, menghapus penyebaran yang ada sekali cukup untuk menyelesaikan masalah, termasuk untuk build DevOps dan menyebarkan alur.
Jika Anda menentukan bahwa menghapus penyebaran sebelumnya selalu diperlukan saat alur build dan deploy DevOps sedang digunakan, Anda dapat menambahkan langkah untuk sementara ke alur build untuk menghapus penyebaran sebelumnya untuk setiap penyebaran baru hingga Anda memecahkan masalah penyebab pasti kerusakan.
Mengatasi kegagalan pemeriksaan integritas
Saat Blazor WebAssembly mengunduh file startup aplikasi, ia menginstruksikan browser untuk melakukan pemeriksaan integritas pada respons. Blazor mengirim nilai hash SHA-256 untuk DLL (.dll
), WebAssembly (.wasm
), dan file lain dalam blazor.boot.json
file, yang tidak di-cache pada klien. Hash file dari file yang di-cache dibandingkan dengan hash dalam blazor.boot.json
file. Untuk file cache dengan hash yang cocok, Blazor menggunakan file yang di-cache. Jika tidak, file diminta dari server. Setelah file diunduh, hash-nya diperiksa lagi untuk validasi integritas. Kesalahan dihasilkan oleh browser jika ada pemeriksaan integritas file yang diunduh gagal.
BlazorAlgoritma untuk mengelola integritas file:
- Memastikan bahwa aplikasi tidak berisiko memuat sekumpulan file yang tidak konsisten, misalnya jika penyebaran baru diterapkan ke server web Anda saat pengguna sedang dalam proses mengunduh file aplikasi. File yang tidak konsisten dapat mengakibatkan aplikasi yang tidak berfungsi.
- Memastikan browser pengguna tidak pernah menyimpan respons yang tidak konsisten atau tidak valid, yang dapat mencegah aplikasi dimulai bahkan jika pengguna me-refresh halaman secara manual.
- Membuatnya aman untuk menyimpan respons dan tidak memeriksa perubahan sisi server sampai hash SHA-256 yang diharapkan berubah sendiri, sehingga pemuatan halaman berikutnya melibatkan lebih sedikit permintaan dan menyelesaikan lebih cepat.
Jika server web mengembalikan respons yang tidak cocok dengan hash SHA-256 yang diharapkan, kesalahan yang mirip dengan contoh berikut muncul di konsol pengembang browser:
Gagal menemukan hash yang valid dalam atribut 'integritas' untuk sumber daya 'https://myapp.example.com/_framework/MyBlazorApp.dll' dengan integritas SHA-256 komputasi 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. Sumber daya telah diblokir.
Dalam kebanyakan kasus, peringatan tidak menunjukkan masalah dengan pemeriksaan integritas. Sebaliknya, peringatan biasanya berarti bahwa beberapa masalah lain ada.
Untuk Blazor WebAssemblysumber referensi boot, lihat Boot.WebAssembly.ts
file di dotnet/aspnetcore
repositori GitHub.
Catatan
Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).
Mendiagnosis masalah integritas
Saat aplikasi dibuat, manifes yang dihasilkan blazor.boot.json
menjelaskan hash SHA-256 sumber daya boot pada saat output build diproduksi. Pemeriksaan integritas lolos selama hash SHA-256 sesuai blazor.boot.json
dengan file yang dikirimkan ke browser.
Alasan umum mengapa hal ini gagal meliputi:
- Respons server web adalah kesalahan (misalnya, 404 - Tidak Ditemukan atau 500 - Kesalahan Server Internal) alih-alih file yang diminta browser. Ini dilaporkan oleh browser sebagai kegagalan pemeriksaan integritas dan bukan sebagai kegagalan respons.
- Sesuatu telah mengubah konten file antara build dan pengiriman file ke browser. Ini mungkin terjadi:
- Jika Anda atau alat build memodifikasi output build secara manual.
- Jika beberapa aspek proses penyebaran memodifikasi file. Misalnya jika Anda menggunakan mekanisme penyebaran berbasis Git, ingatlah bahwa Git secara transparan mengonversi akhir baris gaya Windows ke akhiran baris gaya Unix jika Anda menerapkan file di Windows dan memeriksanya di Linux. Mengubah akhiran baris file mengubah hash SHA-256. Untuk menghindari masalah ini, pertimbangkan untuk menggunakan
.gitattributes
untuk memperlakukan artefak build sebagaibinary
file. - Server web memodifikasi isi file sebagai bagian dari penyajiannya. Misalnya, beberapa jaringan distribusi konten (CDN) secara otomatis mencoba untuk menambang HTML, sehingga memodifikasinya. Anda mungkin perlu menonaktifkan fitur tersebut.
- File
blazor.boot.json
gagal dimuat dengan benar atau tidak di-cache pada klien. Penyebab umum termasuk salah satu hal berikut:- Kode pengembang kustom yang salah dikonfigurasi atau tidak berfungsi.
- Satu atau beberapa lapisan penembolokan perantara yang salah dikonfigurasi.
Untuk mendiagnosis mana dari ini yang berlaku dalam kasus Anda:
- Perhatikan file mana yang memicu kesalahan dengan membaca pesan kesalahan.
- Buka alat pengembang browser Anda dan lihat di tab Jaringan . Jika perlu, muat ulang halaman untuk melihat daftar permintaan dan respons. Temukan file yang memicu kesalahan dalam daftar tersebut.
- Periksa kode status HTTP dalam respons. Jika server mengembalikan apa pun selain 200 - OK (atau kode status 2xx lainnya), maka Anda memiliki masalah sisi server untuk didiagnosis. Misalnya, kode status 403 berarti ada masalah otorisasi, sedangkan kode status 500 berarti server gagal dengan cara yang tidak ditentukan. Konsultasikan log sisi server untuk mendiagnosis dan memperbaiki aplikasi.
- Jika kode status adalah 200 - OK untuk sumber daya, lihat konten respons di alat pengembang browser dan periksa apakah konten cocok dengan data yang diharapkan. Misalnya, masalah umumnya adalah salah mengonfigurasi perutean sehingga permintaan mengembalikan data Anda
index.html
bahkan untuk file lain. Pastikan bahwa respons terhadap.wasm
permintaan adalah biner WebAssembly dan bahwa respons terhadap.dll
permintaan adalah biner rakitan .NET. Jika tidak, Anda memiliki masalah perutean sisi server untuk didiagnosis. - Cari untuk memvalidasi output aplikasi yang diterbitkan dan disebarkan dengan skrip PowerShell integritas Pemecahan Masalah.
Jika Anda mengonfirmasi bahwa server mengembalikan data yang benar secara biasa, harus ada sesuatu yang lain yang memodifikasi konten di antara build dan pengiriman file. Untuk menyelidiki hal ini:
- Periksa mekanisme toolchain build dan penyebaran jika mereka memodifikasi file setelah file dibuat. Contohnya adalah ketika Git mengubah akhiran baris file, seperti yang dijelaskan sebelumnya.
- Periksa server web atau konfigurasi CDN jika disiapkan untuk memodifikasi respons secara dinamis (misalnya, mencoba untuk memangkas HTML). Tidak masalah bagi server web untuk menerapkan kompresi HTTP (misalnya, mengembalikan
content-encoding: br
ataucontent-encoding: gzip
), karena ini tidak memengaruhi hasil setelah dekompresi. Namun, tidak masalah bagi server web untuk memodifikasi data yang tidak dikompresi.
Memecahkan masalah skrip PowerShell integritas
integrity.ps1
Gunakan skrip PowerShell untuk memvalidasi aplikasi yang diterbitkan dan disebarkanBlazor. Skrip disediakan untuk PowerShell Core 7 atau yang lebih baru sebagai titik awal ketika aplikasi memiliki masalah integritas yang Blazor tidak dapat diidentifikasi oleh kerangka kerja. Kustomisasi skrip mungkin diperlukan untuk aplikasi Anda, termasuk jika berjalan pada versi PowerShell yang lebih baru dari versi 7.2.0.
Skrip memeriksa file di publish
folder dan diunduh dari aplikasi yang disebarkan untuk mendeteksi masalah dalam berbagai manifes yang berisi hash integritas. Pemeriksaan ini harus mendeteksi masalah yang paling umum:
- Anda memodifikasi file dalam output yang diterbitkan tanpa menyadarinya.
- Aplikasi ini tidak disebarkan dengan benar ke target penyebaran, atau sesuatu berubah dalam lingkungan target penyebaran.
- Ada perbedaan antara aplikasi yang disebarkan dan output dari penerbitan aplikasi.
Panggil skrip dengan perintah berikut dalam shell perintah PowerShell:
.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}
Dalam contoh berikut, skrip dijalankan pada aplikasi yang berjalan secara lokal di https://localhost:5001/
:
.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\
Tempat penampung:
{BASE URL}
: URL aplikasi yang disebarkan. Garis miring berikutnya (/
) diperlukan.{PUBLISH OUTPUT FOLDER}
: Jalur ke folder atau lokasi aplikasipublish
tempat aplikasi diterbitkan untuk penyebaran.
Catatan
Saat mengkloning repositori dotnet/AspNetCore.Docs
GitHub, integrity.ps1
skrip mungkin dikarantina oleh Bitdefender atau pemindai virus lain yang ada di sistem. Biasanya, file terjebak oleh teknologi pemindai heuristik pemindai virus, yang hanya mencari pola dalam file yang mungkin menunjukkan adanya malware. Untuk mencegah pemindai virus mengkarantina file, tambahkan pengecualian ke pemindai virus sebelum mengkloning repositori. Contoh berikut adalah jalur umum ke skrip pada sistem Windows. Sesuaikan jalur sesuai kebutuhan untuk sistem lain. Tempat {USER}
penampung adalah segmen jalur pengguna.
C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1
Peringatan: Membuat pengecualian pemindai virus berbahaya dan hanya boleh dilakukan ketika Anda yakin bahwa file aman.
Membandingkan checksum file dengan nilai checksum yang valid tidak menjamin keamanan file, tetapi memodifikasi file dengan cara yang mempertahankan nilai checksum tidak sepele untuk pengguna berbahaya. Oleh karena itu, checksum berguna sebagai pendekatan keamanan umum. Bandingkan checksum file lokal integrity.ps1
dengan salah satu nilai berikut:
- SHA256:
32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
- MD5:
9cee7d7ec86ee809a329b5406fbf21a8
Dapatkan checksum file pada OS Windows dengan perintah berikut. Berikan jalur dan nama file untuk {PATH AND FILE NAME}
tempat penampung dan tunjukkan jenis checksum yang akan dihasilkan untuk {SHA512|MD5}
tempat penampung, baik SHA256
atau MD5
:
CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}
Jika Anda memiliki penyebab kekhawatiran bahwa validasi checksum tidak cukup aman di lingkungan Anda, konsultasikan dengan kepemimpinan keamanan organisasi Anda untuk mendapatkan panduan.
Untuk informasi selengkapnya, lihat Gambaran umum perlindungan ancaman berdasarkan Antivirus Microsoft Defender.
Menonaktifkan pemeriksaan integritas untuk aplikasi non-PWA
Dalam kebanyakan kasus, jangan nonaktifkan pemeriksaan integritas. Menonaktifkan pemeriksaan integritas tidak menyelesaikan masalah mendasar yang telah menyebabkan respons yang tidak terduga dan mengakibatkan kehilangan manfaat yang tercantum sebelumnya.
Mungkin ada kasus di mana server web tidak dapat diandalkan untuk mengembalikan respons yang konsisten, dan Anda tidak memiliki pilihan selain menonaktifkan pemeriksaan integritas untuk sementara waktu sampai masalah yang mendasar diselesaikan.
Untuk menonaktifkan pemeriksaan integritas, tambahkan yang berikut ini ke grup properti di Blazor WebAssembly file proyek aplikasi (.csproj
):
<BlazorCacheBootResources>false</BlazorCacheBootResources>
BlazorCacheBootResources
juga menonaktifkan Blazorperilaku default penembolokan .dll
file , .wasm
, dan file lain berdasarkan hash SHA-256 mereka karena properti menunjukkan bahwa hash SHA-256 tidak dapat diandalkan untuk kebenaran. Bahkan dengan pengaturan ini, cache HTTP normal browser mungkin masih menyimpan file-file tersebut, tetapi apakah ini terjadi tergantung pada konfigurasi server web Anda atau tidak dan cache-control
header yang dilayaninya.
Catatan
Properti BlazorCacheBootResources
tidak menonaktifkan pemeriksaan integritas untuk Progressive Web Applications (PWAs). Untuk panduan yang berkaitan dengan PWAs, lihat bagian Menonaktifkan pemeriksaan integritas untuk PWAs .
Kami tidak dapat memberikan daftar lengkap skenario di mana menonaktifkan pemeriksaan integritas diperlukan. Server dapat menjawab permintaan dengan cara arbitrer di luar cakupan Blazor kerangka kerja. Kerangka kerja menyediakan BlazorCacheBootResources
pengaturan untuk membuat aplikasi dapat dijalankan dengan biaya kehilangan jaminan integritas yang dapat disediakan aplikasi. Sekali lagi, kami tidak menyarankan menonaktifkan pemeriksaan integritas, terutama untuk penyebaran produksi. Pengembang harus berusaha menyelesaikan masalah integritas yang mendasar yang menyebabkan pemeriksaan integritas gagal.
Beberapa kasus umum yang dapat menyebabkan masalah integritas adalah:
- Berjalan di HTTP di mana integritas tidak dapat diperiksa.
- Jika proses penyebaran Anda memodifikasi file setelah diterbitkan dengan cara apa pun.
- Jika host Anda memodifikasi file dengan cara apa pun.
Menonaktifkan pemeriksaan integritas untuk PWAs
BlazorTemplat Aplikasi Web Progresif (PWA) berisi file yang disarankan service-worker.published.js
yang bertanggung jawab untuk mengambil dan menyimpan file aplikasi untuk penggunaan offline. Ini adalah proses terpisah dari mekanisme startup aplikasi normal dan memiliki logika pemeriksaan integritas terpisah.
service-worker.published.js
Di dalam file, baris berikut ada:
.map(asset => new Request(asset.url, { integrity: asset.hash }));
Untuk menonaktifkan pemeriksaan integritas, hapus integrity
parameter dengan mengubah baris ke yang berikut:
.map(asset => new Request(asset.url));
Sekali lagi, menonaktifkan pemeriksaan integritas berarti Anda kehilangan jaminan keamanan yang ditawarkan oleh pemeriksaan integritas. Misalnya, ada risiko bahwa jika browser pengguna menyimpan cache aplikasi pada saat yang tepat bahwa Anda menyebarkan versi baru, itu dapat menyimpan beberapa file dari penyebaran lama dan beberapa dari penyebaran baru. Jika itu terjadi, aplikasi akan macet dalam keadaan rusak sampai Anda menyebarkan pembaruan lebih lanjut.
ASP.NET Core