Menghosting dan menyebarkan ASP.NET Core Blazor WebAssembly

Artikel ini menjelaskan cara menghosting dan menyebarkan Blazor WebAssembly menggunakan ASP.NET Core, Content Delivery Networks (CDN), server file, dan Halaman GitHub.

Dengan model hosting :

• Aplikasi Blazor , dependensinya, dan runtime .NET diunduh ke browser secara paralel.
• Aplikasi ini dijalankan langsung di utas UI browser.

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.

Kurangi ukuran heap maksimum untuk beberapa browser pada perangkat seluler

<EmccMaximumHeapSize>268435456</EmccMaximumHeapSize>

Untuk informasi selengkapnya tentang properti dan target MSBuild Mono/WebAssembly, lihat WasmApp.Common.targets (dotnet/runtime repositori GitHub).

<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

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

Perbarui aplikasi untuk menggunakan dekoder.

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

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

Setelah tag <script> milik Blazor 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.

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

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

<PropertyGroup>
  <CompressionEnabled>false</CompressionEnabled>
</PropertyGroup>

dotnet publish -p:CompressionEnabled=false

<PropertyGroup>
  <BlazorEnableCompression>false</BlazorEnableCompression>
</PropertyGroup>

dotnet publish -p:BlazorEnableCompression=false

Menulis ulang URL untuk perutean yang benar

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: 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 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 bagian IIS .

<SelfContained>false</SelfContained>

<RuntimeIdentifier>{RID}</RuntimeIdentifier>

<SelfContained>false</SelfContained>

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 deployment mandiri diterbitkan ke dalam folder /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot atau bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish\ (tergantung pada versi .NET SDK yang digunakan), di mana {TARGET FRAMEWORK} placeholder adalah framework 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:

• Menyebarkan dari Visual Studio
• Menyebarkan dari Visual Studio Code
• Sebarkan dari GitHub

Sebarkan dari Visual Studio

Untuk menyebarkan dari Visual Studio, buat profil penerbitan untuk Azure Static Web Apps:

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

2. Di UI Terbitkan Visual Studio, pilih Target>Azure>Target Spesifik>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 detail penyebaran>Sumber 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. CLI SWA 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 andal untuk aplikasi Blazor. Untuk mengonfigurasi IIS untuk menghosting Blazor, lihat Membangun Situs Web Statis di IIS.

Aset yang diterbitkan dibuat di folder /bin/Release/{TARGET FRAMEWORK}/publish atau bin\Release\{TARGET FRAMEWORK}\browser-wasm\publish, tergantung pada versi SDK mana yang digunakan dan di mana {TARGET FRAMEWORK} placeholder adalah kerangka kerja target. Host konten folder publish 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 routing fallback SPA agar permintaan untuk aset non-file dialihkan ke dokumen bawaan aplikasi di dalam folder aset statisnya (wwwroot/index.html).

Gunakan web.config kustom

Untuk menggunakan file kustom web.config :

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 Blazor WebAssembly atau /bin/Release/{TARGET FRAMEWORK}/publish/wwwroot, tergantung pada versi SDK mana yang digunakan dan di mana {TARGET FRAMEWORK} adalah kerangka kerja target, atur properti <PublishIISAssets> ke true dalam file proyek (.csproj). 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 aplikasi Blazor yang diterbitkan di file web.config dengan menambahkan bagian <handlers> ke bagian <system.webServer> dari file:

  <handlers>
    <remove name="aspNetCore" />
  </handlers>
  

• Nonaktifkan pewarisan bagian <system.webServer> dari aplikasi root (induk) menggunakan elemen <location> 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 dari aplikasi dengan mengikuti panduan di artikel Host dan deploy ASP.NET Core Blazor.

Kompresi Brotli dan Gzip

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 mensyaratkan salah satu dari berikut:
  • Menyediakan 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 IIS Manager menghasilkan kesalahan saat mencoba mengakses konfigurasi situs web, pastikan bahwa Modul URL Rewrite telah terpasang. Saat modul tidak diinstal, web.config file tidak dapat diurai oleh IIS. Ini mencegah Manajer IIS memuat konfigurasi situs web dan mencegah situs web menyajikan file statis Blazor.

Untuk informasi selengkapnya tentang pemecahan masalah penyebaran ke IIS, lihat Memecahkan masalah ASP.NET Core di Azure App Service dan IIS.

Azure Storage

Azure Storage untuk hosting file statis memungkinkan hosting aplikasi tanpa memerlukan 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 dan harus ditangani oleh Blazor router, kesalahan 404 - Tidak Ditemukan yang dihasilkan oleh layanan blob merutekan permintaan ke jalur dokumen error Error document path. 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 lebih lanjut tentang konfigurasi server web NGINX produksi, lihat Membuat File Konfigurasi NGINX Plus dan NGINX.

Apache

Untuk menyebarkan Blazor WebAssembly aplikasi ke Apache:

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} sebagai tempat penampung framework target) ke dalam direktori /var/www/blazorapp (lokasi yang ditentukan oleh DocumentRoot dalam file konfigurasi).

3. Mulai ulang layanan Apache.

Untuk informasi lebih lanjut, lihat mod_mime dan mod_deflate.

GitHub Pages

Panduan berikut untuk penyebaran aplikasi Blazor WebAssembly ke GitHub Pages memperlihatkan konsep dengan alat langsung yang sudah terpasang di GitHub Pages. Alat ini digunakan oleh penulis dokumentasi ASP.NET Core untuk membuat tautan referensi silang (XREF) ke dokumentasi API untuk markdown artikel:

• BlazorWebAssemblyXrefGenerator aplikasi sampel (blazor-samples/BlazorWebAssemblyXrefGenerator)
• situs web Live Xref Generator

Pengaturan Halaman GitHub

• Tindakan>Umum
  • izin Tindakan
    • Izinkan tindakan perusahaan, dan pilih tindakan non-perusahaan serta alur kerja yang dapat digunakan kembali> Diaktifkan (dipilih)
    • Izinkan tindakan yang dibuat oleh GitHub> Diaktifkan (dipilih)
    • Izinkan tindakan dan alur kerja yang dapat digunakan kembali>stevesandersonms/ghaction-rewrite-base-href@v1,
  • izin Alur Kerja >Izin membaca repositori dan paket
• Pages>Pembangunan dan penerapan
  • Source>Tindakan GitHub
  • Alur kerja terpilih: HTML Statis dan dasarkan skrip Aksi penyebaran statis Anda pada file Xref Generator static.yml untuk alat Xref Generator. Konfigurasi dalam file dijelaskan di bagian berikutnya.
  • Domain kustom: Atur jika Anda berniat menggunakan domain kustom, yang tidak tercakup dalam panduan ini. Untuk informasi selengkapnya, lihat Mengonfigurasi domain kustom untuk situs Halaman GitHub Anda.
  • Terapkan HTTPS> Diaktifkan (dipilih)

Konfigurasi skrip penyebaran statis

Generator Xref static.yml file

Konfigurasikan entri berikut dalam skrip untuk penyebaran Anda:

• Terbitkan direktori (PUBLISH_DIR): Gunakan jalur ke folder repositori tempat aplikasi Blazor WebAssembly diterbitkan. Aplikasi ini dikompilasi untuk versi .NET tertentu, dan segmen jalur versi tersebut harus sesuai. Contoh: BlazorWebAssemblyXrefGenerator/bin/Release/net9.0/publish/wwwroot adalah jalur untuk aplikasi yang mengadopsi Target Framework Moniker (TFM) net9.0 untuk .NET 9.0 SDK
• Jalur push (on:push:paths): Atur jalur push agar sesuai dengan folder repo aplikasi menggunakan wildcard **. Contoh: BlazorWebAssemblyXrefGenerator/**
• Versi .NET SDK (dotnet-version lewat actions/setup-dotnet Tindakan): Saat ini, tidak ada cara untuk mengatur versi ke "terbaru" (lihat Izinkan penentuan 'terbaru' sebagai versi dotnet (actions/setup-dotnet #497) untuk memberi suara pada permintaan fitur). Atur versi SDK setidaknya setingkat versi kerangka kerja aplikasi.
• Jalur publikasi ( perintahdotnet publish): Atur jalur terbitkan folder ke folder repositori aplikasi. Contoh: dotnet publish BlazorWebAssemblyXrefGenerator -c Release
• HREF Dasar (base_href untuk SteveSandersonMS/ghaction-rewrite-base-href Aksi): Atur href dasar untuk aplikasi menjadi nama repositori. Contoh: Pemilik repositori sampel Blazor adalah dotnet. Nama repositori sampel Blazor adalah blazor-samples. Ketika alat Generator Xref disebarkan ke Halaman GitHub, alamat webnya didasarkan pada nama repositori (https://dotnet.github.io/blazor-samples/). Href dasar dari aplikasi adalah /blazor-samples/, yang diatur menjadi base_href supaya Action ghaction-rewrite-base-href dapat menulis ke dalam tag wwwroot/index.html<base> dari aplikasi saat aplikasi di-deploy. Untuk informasi selengkapnya, lihat Host dan sebarkan ASP.NET Core Blazor.

Server Ubuntu yang dihosting GitHub (terbaru) memiliki versi .NET SDK yang telah diinstal sebelumnya. Anda dapat menghapus langkah Tindakan dari skrip jika .NET SDK yang telah diinstal sebelumnya sudah cukup untuk mengkompilasi aplikasi. Untuk menentukan .NET SDK yang diinstal untuk ubuntu-latest:

1. Pergi ke bagian Gambar Tersedia dari repositori GitHub actions/runner-images.
2. Temukan gambar ubuntu-latest, yang merupakan baris tabel pertama.
3. Pilih tautan di kolom Included Software.
4. Gulir ke bawah ke bagian .NET Tools untuk melihat .NET Core SDK yang diinstal dengan gambar.

Catatan Penerapan

GitHub Action bawaan, yang mengunggah halaman, mengabaikan pengunggahan folder yang diawali dengan garis bawah, folder _framework misalnya. Untuk menyebarkan folder yang dimulai dengan garis bawah, tambahkan file .nojekyll kosong ke akar repositori aplikasi. Contoh: Xref Generator .nojekyll file

Lakukan langkah ini sebelum penyebaran aplikasi pertama: Git memperlakukan file JavaScript (JS), seperti blazor.webassembly.js, sebagai teks dan mengonversi akhir baris dari CRLF (pengembalian kereta dan umpan baris) 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 file .gitattributes dengan baris *.js binary sebelum menambahkan aset aplikasi ke cabang Git. Baris konfigurasi *.js binary mengatur Git untuk memperlakukan JS sebagai file biner, yang menghindari pemrosesan file dalam alur penyebaran. Hash file dari file yang belum diproses cocok dengan entri dalam file blazor.boot.json, dan pemeriksaan integritas di sisi klien berhasil. Untuk informasi selengkapnya, lihat ASP.NET Core runtime Blazor WebAssembly dan penembolokan bundel aplikasi .NET. Contoh: Xref Generator .gitattributes file

Untuk menangani penulisan ulang URL berdasarkan Aplikasi Halaman Tunggal untuk GitHub Pages (rafrex/spa-github-pages repositori GitHub):

• Tambahkan file wwwroot/404.html dengan skrip yang menangani pengalihan permintaan ke halaman index.html. Contoh: Xref Generator 404.html file
• Di wwwroot/index.html, tambahkan skrip ke konten <head>. Contoh: Xref Generator index.html file

Halaman GitHub tidak secara asli mendukung penggunaan sumber daya yang dikompresi Brotli. Untuk menggunakan Brotli:

• Tambahkan skrip wwwroot/decode.js ke folder wwwroot aplikasi. Contoh: Xref Generator decode.js file

• Tambahkan tag <script> untuk memuat skrip decode.js dalam file wwwroot/index.html tepat di atas tag <script> yang memuat skrip Blazor. Contoh: Xref Generator index.html file

  • Atur autostart="false" untuk skrip Blazor WebAssembly.
  • Tambahkan skrip loadBootResource setelah tag <script> yang memuat skrip Blazor WebAssembly. Contoh: Xref Generator index.html file

• Tambahkan file robots.txt dan sitemap.txt untuk meningkatkan SEO. Contoh: Xref Generator robots.txt file, Xref Generator sitemap.txt file

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:

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

• 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 Properti>Debug>Argumen aplikasi. 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 di Properti>Debug>Argumen Aplikasi. Mengatur argumen di halaman properti Visual Studio menambahkan argumen ke launchSettings.json file.

  --urls=http://127.0.0.1:0
  

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

((Get-Content {PATH}\service-worker-assets.js -Raw) -replace '.dll"','.bin"') | Set-Content {PATH}\service-worker-assets.js

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

sed -i 's/\.dll"/.bin"/g' {PATH}/service-worker-assets.js

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

((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

<Target Name="ChangeDLLFileExtensions" AfterTargets="AfterPublish" Condition="'$(Configuration)'=='Release'">
  <Exec Command="powershell.exe -command &quot;&amp; { .\ChangeDLLExtensions.ps1 '$(SolutionDir)' '$(TargetFramework)'}&quot;" />
</Target>

<staticContent>
  ...
  <mimeMap fileExtension=".bin" mimeType="application/octet-stream" />
  ...
</staticContent>

<mimeMap fileExtension=".bin.br" mimeType="application/octet-stream" />
<mimeMap fileExtension=".bin.gz" mimeType="application/octet-stream" />

- <mimeMap fileExtension=".dll" mimeType="application/octet-stream" />

- <mimeMap fileExtension=".dll.br" mimeType="application/octet-stream" />
- <mimeMap fileExtension=".dll.gz" mimeType="application/octet-stream" />

Kerusakan penyebaran 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.

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 akan 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.
• Menjamin keamanan penyimpanan tanggapan dan tidak memeriksa perubahan di sisi server hingga hash SHA-256 yang diharapkan itu sendiri berubah, sehingga pemuatan halaman berikutnya melibatkan lebih sedikit permintaan dan dapat diselesaikan 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 digest yang valid dalam atribut 'integritas' untuk sumber daya 'https://myapp.example.com/_framework/MyBlazorApp.dll' dengan integritas SHA-256 yang dihitung '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 referensi sumber boot Blazor WebAssembly, lihat file Boot.WebAssembly.ts di repositori dotnet/aspnetcore GitHub.

Mendiagnosis masalah integritas

Saat aplikasi dibangun, manifes yang dihasilkan blazor.boot.json menjelaskan hash SHA-256 sumber daya boot pada saat output build dibuat. Pemeriksaan integritas dianggap berhasil selama hash SHA-256 di blazor.boot.json sesuai 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 dalam proses penyebaran telah 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 memperkecil 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 penyimpanan sementara 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. Sebagai contoh, masalah yang sering terjadi adalah salah mengonfigurasi perutean sehingga permintaan dapat 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 yang perlu didiagnosis.
5. Gunakan skrip PowerShell Pemecahan Masalah untuk Memeriksa Integritas guna memvalidasi output aplikasi yang diterbitkan dan disebarkan.

Jika Anda mengonfirmasi bahwa server mengembalikan data yang kemungkinan benar, harus ada sesuatu yang lain yang memodifikasi konten di antara proses pembuatan dan pengiriman berkas. Untuk menyelidiki hal ini:

• Periksa toolchain build dan mekanisme penyebaran jika ada modifikasi pada file setelah file tersebut dibuat. Contohnya adalah ketika Git mengubah akhiran baris file, seperti yang dijelaskan sebelumnya.
• Periksa konfigurasi server web atau CDN apabila dikonfigurasi untuk memodifikasi respons secara dinamis (misalnya, mencoba untuk memperkecil 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 integritas skrip PowerShell

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 di akhir (/) diperlukan.
• {PUBLISH OUTPUT FOLDER}: Jalur ke folder atau lokasi aplikasi publish tempat aplikasi diterbitkan untuk penyebaran.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

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 Blazor perilaku default penembolokan .dll file .wasm, dan file lain berdasarkan hash SHA-256 mereka karena atribut 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.

Kami tidak dapat memberikan daftar lengkap skenario di mana menonaktifkan pemeriksaan integritas diperlukan. Server-server dapat menjawab permintaan dengan cara sembarang di luar cakupan kerangka kerja Blazor. Kerangka kerja menyediakan BlazorCacheBootResources pengaturan agar aplikasi dapat dijalankan dengan mengorbankan jaminan integritas yang dapat dijamin oleh aplikasi. Sekali lagi, kami tidak menyarankan untuk menonaktifkan pemeriksaan integritas, terutama untuk penggunaan 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) service-worker.published.js berisi file yang disarankan yang bertanggung jawab untuk mengambil serta 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.