Menghosting dan menyebarkan ASP.NET Core Blazor WebAssembly

Artikel ini menjelaskan cara menghosting dan menyebarkan aplikasi Blazor WebAssembly.

Dengan model hosting :

• Aplikasi Blazor , dependensinya, dan runtime .NET diunduh ke browser secara paralel.
• Aplikasi ini dijalankan langsung di utas antarmuka pengguna 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 di bagian Penyebaran mandiri dan artikel lain dalam simpul ini untuk IIS, layanan Azure, Halaman Apache, Nginx, dan GitHub.

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 basis aplikasi. Untuk informasi selengkapnya dan tautan silang untuk panduan lebih lanjut tentang hosting sub-aplikasi IIS, lihat Host dan sebarkan ASP.NET Core Blazor.

Kurangi ukuran heap maksimum untuk beberapa browser pada perangkat seluler

Saat membangun aplikasi Blazor yang berjalan di klien, yaitu proyek .Client dari aplikasi Blazor Web App atau aplikasi mandiri Blazor WebAssembly, dan menargetkan browser perangkat seluler, terutama Safari di iOS, mungkin diperlukan untuk mengurangi memori maksimum menggunakan properti MSBuild EmccMaximumHeapSize. 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 perakitan .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 bawaan ketika 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 ASP.NET Core Blazor startup.

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:

• Brotli (tingkat tertinggi)
• Gzip

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:

• 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 diperkecil diberi nama decode.min.js dan ditemukan di folder js dalam repositori.

Nota

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.

Dalam file wwwroot/index.html, atur autostart ke false pada tag Blazor<script>.

<script src="_framework/blazor.webassembly.js" autostart="false"></script>

Setelah tag Blazor milik <script> dan sebelum tag penutup </body>, tambahkan blok kode JavaScript berikut ini <script>. Fungsi berikut memanggil fetch dengan cache: 'no-cache' untuk menjaga cache browser tetap diperbarui.

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 ASP.NET Core Blazor startup.

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

Mengubah URL untuk pengarahan yang tepat

Permintaan perutean untuk komponen halaman dalam aplikasi Blazor WebAssembly tidak sesederhana permintaan perutean di aplikasi Blazor Server. Pertimbangkan aplikasi Blazor WebAssembly dengan dua komponen:

• Main.razor: Memuat di akar aplikasi dan berisi tautan ke komponen About (href="About").
• About.razor: komponen About.

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 mem-bootstrapi aplikasi.
4. Komponen Router dimuat, dan komponen RazorMain dirender.

Di Halaman Utama, memilih tautan ke komponen About berfungsi di klien karena router Blazor menghentikan browser melakukan permintaan di Internet ke www.contoso.com untuk About dan melayani komponen About yang telah dirender itu sendiri. Semua permintaan untuk endpoint internal dalam aplikasi Blazor WebAssembly berfungsi dengan cara yang sama: Permintaan tidak memicu permintaan berbasis browser ke sumber daya yang di-host oleh 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 kendali dan merespons dengan sumber daya yang sesuai.

Saat menyebarkan ke server IIS, Anda dapat menggunakan modul URL Rewrite dengan file web.config aplikasi yang telah diterbitkan. Untuk informasi selengkapnya, lihat Menghosting dan menyebarkan ASP.NET Core Blazor WebAssembly dengan IIS.

Penyebaran mandiri

Penerapan mandiri menyediakan 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 folder /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot atau bin/Release/{TARGET FRAMEWORK}/browser-wasm/publish, di mana {TARGET FRAMEWORK} adalah tempat penampung 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.

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 Nginx 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:

• Artikel Nginx atau Apache
• Dokumentasi Docker

Nilai konfigurasi host

Blazor WebAssembly aplikasi dapat menerima nilai konfigurasi host berikut sebagai argumen baris perintah saat runtime di lingkungan pengembangan.

Sumber 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 baris 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 ketika aplikasi dijalankan dengan Visual Studio Debugger dan dari prompt perintah menggunakan dotnet watch (atau dotnet run).

  "commandLineArgs": "--contentroot=/content-root-path"
  

• Di Visual Studio, tentukan argumen dalam Properties>Debug>argumen Aplikasi. Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke launchSettings.json file.

  --contentroot=/content-root-path
  

Dasar 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 ASP.NET CoreBlazor.

Penting

Tidak seperti jalur yang disediakan untuk href dari tag <base>, jangan sertakan garis miring berikutnya (/) saat meneruskan nilai argumen --pathbase. 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 baris 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 Properties>Debug>argumen Aplikasi. Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke launchSettings.json file.

  --pathbase=/relative-URL-path
  

Untuk informasi selengkapnya, lihat jalur dasar aplikasi ASP.NET CoreBlazor.

URL

Argumen --urls mengatur alamat IP atau alamat host dengan port dan protokol untuk mendengarkan permintaan.

• Teruskan argumen saat menjalankan aplikasi secara lokal pada baris 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 Properties>Debug>argumen Aplikasi. Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke launchSettings.json file.

  --urls=http://127.0.0.1:0
  

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.

Kerusakan implementasi sebelumnya

Biasanya saat penerapan:

• 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 tertinggal 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 sudah ada cukup untuk menyelesaikan masalah, termasuk untuk build DevOps dan pipeline deploy.

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.