Bagikan melalui


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 ke About komponen (href="About").
  • About.razor: About komponen.

Saat dokumen default aplikasi diminta menggunakan bilah alamat browser (misalnya, https://www.contoso.com/):

  1. Browser membuat permintaan.
  2. Halaman default dikembalikan, yang biasanya index.html.
  3. index.html bootstrap aplikasi.
  4. Router komponen dimuat, dan RazorMain 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:

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=falseMSBuild .

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:

  1. Simpan pekerjaan yang belum disimpan dalam proyek, karena mulai ulang Visual Studio mungkin diperlukan selama proses.

  2. Di UI Terbitkan Visual Studio, pilih Target>Azure>Specific Target>Azure Static Web Apps untuk membuat profil penerbitan.

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

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

  5. 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).

Menggunakan kustom web.config

Untuk menggunakan file kustom web.config :

  1. Tempatkan file kustom web.config di folder akar proyek.
  2. Terbitkan proyek. Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.
  1. Tempatkan file kustom web.config di folder akar proyek. Untuk solusi yang dihosting, tempatkan Blazor WebAssemblyfile di Server folder proyek.
  2. 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 ke true 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 kustom web.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 kustom web.config . Dalam contoh berikut, file kustom web.config ditempatkan oleh pengembang di akar proyek. web.config Jika file berada di tempat lain, tentukan jalur ke file di SourceFiles. Contoh berikut menentukan publish folder dengan $(PublishDir), tetapi menyediakan jalur ke DestinationFolder 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:

  1. 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.
  2. 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 dengan inheritInChildApplications diatur ke false:

    <?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.
  • 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 contoh web.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:

    1. Klik kanan file dan pilih Properti.
    2. 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:

  1. 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>
    
  1. 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>
    
  1. Tempatkan file konfigurasi Apache ke /etc/httpd/conf.d/ dalam direktori.

  2. 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 ditentukan DocumentRoot dalam file konfigurasi).

  3. 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.jsteks 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:

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 dengan dotnet watch (atau dotnet 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 dengan dotnet watch (atau dotnet 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 dengan dotnet watch (atau dotnet 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:

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 dalam service-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 &quot;&amp; { .\ChangeDLLExtensions.ps1 '$(SolutionDir)' '$(TargetFramework)'}&quot;" />
</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 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 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 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.