Bagikan melalui

Blazor WebAssembly ASP.NET Runtime Core .NET dan penembolokan app bundle

  • Artikel

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 9 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 9 dari artikel ini.

Blazor WebAssembly Saat aplikasi dimuat di browser, aplikasi mengunduh sumber daya boot dari server:

  • Kode JavaScript untuk bootstrap aplikasi
  • Runtime dan rakitan .NET
  • Lokalkan data tertentu

Kecuali untuk Blazorfile sumber daya boot (blazor.boot.json), runtime .NET WebAssembly dan file bundel aplikasi di-cache pada klien. File blazor.boot.json berisi manifes file yang membentuk aplikasi yang harus diunduh bersama dengan hash konten file yang digunakan untuk mendeteksi apakah salah satu sumber daya boot telah berubah. Blazorcache mengunduh file menggunakan API Cache browser.

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 lainnya dalam blazor.boot.json file. 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.

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 sebagai binary 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:

  1. Perhatikan file mana yang memicu kesalahan dengan membaca pesan kesalahan.
  2. 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.
  3. 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.
  4. 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.
  5. 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 atau content-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 aplikasi publish 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 penembolokan sumber daya dan 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 .dllfile , .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 penembolokan sumber daya dan 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.

Sumber Daya Tambahan:

Pemuatan sumber daya boot