Menghosting dan menyebarkan ASP.NET Core Blazor

Artikel ini menjelaskan cara menghosting dan menyebarkan aplikasi Blazor.

Menerbitkan aplikasi

Aplikasi diterbitkan untuk penyebaran dalam konfigurasi Rilis.

Visual Studio

1. Pilih perintah Terbitkan {APPLICATION} dari menu Build, tempat {APPLICATION} tempat penampung nama aplikasi.
2. Pilih terbitkan target. Untuk menerbitkan secara lokal, pilih Folder.
3. Terima lokasi default di bidang Pilih folder atau tentukan lokasi lain. Pilih tombol Publish.

.NET CLI

Gunakan perintah dotnet publish untuk menerbitkan aplikasi dengan konfigurasi Rilis:

dotnet publish -c Release

Menerbitkan aplikasi akan memicu pemulihan dependensi proyek dan membangun proyek sebelum membuat aset untuk penyebaran. Sebagai bagian dari proses pembangunan, metode dan rangkaian yang tidak digunakan dihapus untuk mengurangi ukuran unduhan aplikasi dan waktu muat.

Terbitkan lokasi:

• Blazor Aplikasi Web: Secara default, aplikasi diterbitkan ke /bin/Release/{TARGET FRAMEWORK}/publish dalam folder. Sebarkan konten dari folder publish ke host.
• Blazor WebAssembly: Secara default, aplikasi diterbitkan ke bin\Release\net8.0\browser-wasm\publish\ dalam folder. Untuk menyebarkan apl sebagai situs statis, salin konten dari folder wwwroot ke host situs statis.

Di {TARGET FRAMEWORK} jalur sebelumnya adalah kerangka kerja target (misalnya, net8.0).

IIS

Untuk menghosting Blazor aplikasi di IIS, lihat sumber daya berikut:

• Hosting IIS
  • Menerbitkan aplikasi ASP.NET Core ke IIS
  • Host ASP.NET Core di Windows dengan IIS
• Host dan sebarkan aplikasi sisi Blazor server ASP.NET Core: Aplikasi server yang berjalan di IIS, termasuk IIS dengan Azure Virtual Machines (VM) yang menjalankan OS Windows dan Azure App Service.
• Host dan sebarkan ASP.NET Core Blazor WebAssembly: Mencakup panduan tambahan untuk Blazor WebAssembly aplikasi yang dihosting di IIS, termasuk hosting situs statis, file kustom web.config , penulisan ulang URL, sub-aplikasi, kompresi, dan hosting file statis Azure Storage.
• Hosting sub-aplikasi IIS
  • Ikuti panduan di bagian Jalur dasar aplikasi untuk Blazor aplikasi sebelum menerbitkan aplikasi. Contoh menggunakan jalur /CoolApp dasar aplikasi dan menunjukkan cara mendapatkan jalur dasar dari pengaturan aplikasi atau penyedia konfigurasi lainnya.
  • Ikuti panduan konfigurasi sub-aplikasi dalam Konfigurasi tingkat lanjut. Jalur folder sub-aplikasi di bawah situs akar menjadi jalur virtual sub-aplikasi. Untuk jalur /CoolAppdasar aplikasi , Blazor aplikasi ditempatkan di folder bernama CoolApp di bawah situs akar dan sub-aplikasi mengambil jalur virtual ./CoolApp

Berbagi kelompok aplikasi di antara aplikasi ASP.NET Core tidak didukung, termasuk untuk aplikasi Blazor. Gunakan satu kelompok aplikasi per aplikasi saat menghosting dengan IIS, dan hindari penggunaan direktori virtual IIS untuk menghosting beberapa aplikasi.

Jalur dasar aplikasi

Jalur dasar aplikasi adalah jalur URL akar aplikasi. Perutean yang berhasil dalam Blazor aplikasi memerlukan konfigurasi kerangka kerja untuk jalur URL akar apa pun yang tidak berada di jalur /dasar aplikasi default .

Pertimbangkan aplikasi ASP.NET Core dan sub-aplikasi Blazor berikut:

• Aplikasi ASP.NET Core diberi nama MyApp:
  • Aplikasi secara fisik berada di d:/MyApp.
  • Permintaan diterima di https://www.contoso.com/{MYAPP RESOURCE}.
• Aplikasi Blazor bernama CoolApp adalah sub-aplikasi dari MyApp:
  • Sub-aplikasi secara fisik berada di d:/MyApp/CoolApp.
  • Permintaan diterima di https://www.contoso.com/CoolApp/{COOLAPP RESOURCE}.

Tanpa menentukan konfigurasi tambahan untuk CoolApp, sub-aplikasi dalam skenario ini tidak memiliki pengetahuan tentang lokasinya di server. Misalnya, aplikasi tidak dapat membuat URL relatif yang benar ke sumber dayanya tanpa mengetahui bahwa itu berada di jalur URL relatif /CoolApp/. Skenario ini juga berlaku di berbagai skenario hosting dan proksi terbalik saat aplikasi tidak dihosting di jalur URL root.

Latar belakang

Tujuan tag jangkar (href) dapat terdiri dengan salah satu dari dua titik akhir:

• Lokasi absolut yang menyertakan skema (default ke skema halaman jika dihilangkan), host, port, dan jalur atau hanya garis miring (/) diikuti oleh jalur.

  Contoh: https://example.com/a/b/c atau /a/b/c

• Lokasi relatif yang hanya berisi jalur dan tidak dimulai dengan garis miring (/). Ini diselesaikan relatif terhadap URL dokumen saat ini atau <base> nilai tag, jika ditentukan.

  Contoh: a/b/c

Kehadiran garis miring berikutnya (/) dalam jalur dasar aplikasi yang dikonfigurasi signifikan untuk menghitung jalur dasar untuk URL aplikasi. Misalnya, https://example.com/a memiliki jalur https://example.com/dasar , sementara https://example.com/a/ dengan garis miring berikutnya memiliki jalur https://example.com/adasar .

Ada tiga sumber tautan yang berkaitan dengan Blazor di aplikasi ASP.NET Core:

• URL dalam Razor komponen (.razor) biasanya relatif.
• URL dalam skrip, seperti Blazor skrip (blazor.*.js), relatif terhadap dokumen.

Jika Anda merender Blazor aplikasi dari dokumen yang berbeda (misalnya, /Admin/B/C/ dan /Admin/D/E/), Anda harus memperhitungkan jalur dasar aplikasi, atau jalur dasar berbeda saat aplikasi merender di setiap dokumen dan sumber daya diambil dari URL yang salah.

Ada dua pendekatan untuk menangani tantangan menyelesaikan tautan relatif dengan benar:

• Petakan sumber daya secara dinamis menggunakan dokumen yang dirender sebagai akar.
• Atur jalur dasar yang konsisten untuk dokumen dan petakan sumber daya di bawah jalur dasar tersebut.

Opsi pertama lebih rumit dan bukan pendekatan yang paling umum, karena membuat navigasi berbeda untuk setiap dokumen. Pertimbangkan contoh berikut untuk merender halaman /Something/Else:

• Dirender di bawah /Admin/B/C/, halaman dirender dengan jalur /Admin/B/C/Something/Else.
• Dirender di bawah /Admin/D/E/, halaman dirender pada jalur yang sama dari /Admin/B/C/Something/Else.

Di bawah pendekatan pertama, penawaran IDynamicEndpointMetadata perutean dan MatcherPolicy, yang dalam kombinasi dapat menjadi dasar untuk menerapkan solusi yang sepenuhnya dinamis yang menentukan pada runtime tentang bagaimana permintaan dirutekan.

Untuk opsi kedua, yang merupakan pendekatan biasa yang diambil, aplikasi mengatur jalur dasar dalam dokumen dan memetakan titik akhir server ke jalur di bawah dasar. Panduan berikut mengadopsi pendekatan ini.

Sisi server Blazor

Petakan SignalR hub aplikasi sisi Blazor server dengan meneruskan jalur ke MapBlazorHubProgram dalam file:

app.MapBlazorHub("base/path");

Manfaat penggunaannya MapBlazorHub adalah Anda dapat memetakan pola, seperti "{tenant}" dan bukan hanya jalur konkret.

Anda juga dapat memetakan SignalR hub saat aplikasi berada di folder virtual dengan alur middleware bercabang. Dalam contoh berikut, permintaan untuk /base/path/ ditangani oleh Blazorhub :SignalR

app.Map("/base/path/", subapp => {
    subapp.UsePathBase("/base/path/");
    subapp.UseRouting();
    subapp.UseEndpoints(endpoints => endpoints.MapBlazorHub());
});

Konfigurasikan <base> tag, sesuai panduan di bagian Konfigurasikan jalur dasar aplikasi.

Mandiri Blazor WebAssembly

Di aplikasi mandiri Blazor WebAssembly , hanya tag yang dikonfigurasi <base> , sesuai panduan di bagian Mengonfigurasi jalur dasar aplikasi.

Mengonfigurasi jalur dasar aplikasi

Untuk menyediakan konfigurasi untuk Blazor jalur https://www.contoso.com/CoolApp/dasar aplikasi , atur jalur dasar aplikasi, yang juga disebut jalur akar relatif.

Dengan mengonfigurasi jalur dasar aplikasi, komponen yang tidak ada di direktori akar dapat membuat URL relatif terhadap jalur akar aplikasi. Komponen di berbagai tingkat struktur direktori dapat membangun tautan ke sumber daya lain pada lokasi di seluruh aplikasi. Jalur dasar aplikasi juga digunakan untuk mencegah hyperlink yang dipilih dengan target href tautan berada dalam ruang URI jalur dasar aplikasi. Komponen Router menangani navigasi internal.

Dalam banyak skenario hosting, jalur URL relatif ke aplikasi adalah akar dari aplikasi. Dalam kasus default ini, jalur dasar URL relatif aplikasi dikonfigurasi / seperti <base href="/" /> dalam <head> konten.

Catatan

Dalam beberapa skenario hosting, seperti Halaman GitHub dan sub-aplikasi IIS, jalur dasar aplikasi harus diatur ke jalur URL relatif aplikasi server.

• Di aplikasi sisi Blazor server, gunakan salah satu pendekatan berikut:

  • Opsi 1: Gunakan <base> tag untuk mengatur jalur dasar aplikasi (lokasi <head> konten):

    <base href="/CoolApp/">
    

    Garis miring berikutnya diperlukan.

  • Opsi 2: Panggil UsePathBaseterlebih dahulu dalam alur pemrosesan permintaan aplikasi (Program.cs) segera setelah WebApplicationBuilder dibuat (builder.Build()) untuk mengonfigurasi jalur dasar untuk middleware berikut yang berinteraksi dengan jalur permintaan:

    app.UsePathBase("/CoolApp");
    

    Memanggil UsePathBase disarankan jika Anda juga ingin menjalankan aplikasi Blazor Server secara lokal. Misalnya, berikan URL peluncuran di Properties/launchSettings.json:

    "launchUrl": "https://localhost:{PORT}/CoolApp",
    

    Tempat penampung {PORT} dalam contoh sebelumnya adalah port yang cocok dengan port aman di jalur konfigurasi applicationUrl. Contoh berikut menunjukkan profil peluncuran lengkap untuk aplikasi di port 7279:

    "BlazorSample": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:7279;http://localhost:5279",
      "launchUrl": "https://localhost:7279/CoolApp",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
    }
    

    Untuk informasi selengkapnya tentang launchSettings.json file, lihat Menggunakan beberapa lingkungan di ASP.NET Core. Untuk informasi tambahan tentang Blazor jalur dan hosting dasar aplikasi, lihat <base href="/" /> atau alternatif tag dasar untuk Blazor integrasi MVC (dotnet/aspnetcore #43191).

• Blazor WebAssembly Mandiri (wwwroot/index.html):

  <base href="/CoolApp/">
  

  Garis miring berikutnya diperlukan.

Catatan

Saat menggunakan WebApplication (lihat Migrasi dari ASP.NET Core 5.0 ke 6.0), app.UseRouting harus dipanggil setelahnya UsePathBase sehingga Middleware Perutean dapat mengamati jalur yang dimodifikasi sebelum mencocokkan rute. Jika tidak, rute dicocokkan sebelum jalur ditulis ulang oleh UsePathBase seperti yang dijelaskan dalam artikel Pengurutan Middleware dan Perutean.

Jangan memberi awalan tautan di seluruh aplikasi dengan garis miring. Hindari penggunaan pemisah segmen jalur atau gunakan notasi jalur relatif garis miring titik (./):

• ❌ Salah: <a href="/account">
• ✔️ Benar: <a href="account">
• ✔️ Benar: <a href="./account">

Dalam permintaan API web Blazor WebAssembly dengan layanan HttpClient, konfirmasikan bahwa JSON helpers (HttpClientJsonExtensions) tidak mengawali URL dengan garis miring (/):

• ❌ Salah: var rsp = await client.GetFromJsonAsync("/api/Account");
• ✔️ Benar: var rsp = await client.GetFromJsonAsync("api/Account");

Jangan mengawali tautan relatif Pengelola Navigasi dengan garis miring. Hindari penggunaan pemisah segmen jalur atau gunakan notasi jalur relatif titik-garis miring (./) (Navigation adalah disuntikkan NavigationManager):

• ❌ Salah: Navigation.NavigateTo("/other");
• ✔️ Benar: Navigation.NavigateTo("other");
• ✔️ Benar: Navigation.NavigateTo("./other");

Dalam konfigurasi umum untuk hosting Azure/IIS, konfigurasi tambahan biasanya tidak diperlukan. Dalam beberapa skenario hosting non-IIS dan hosting proksi terbalik, konfigurasi Middleware File Statis tambahan mungkin diperlukan:

• Untuk melayani file statis dengan benar (misalnya, app.UseStaticFiles("/CoolApp");).
• Untuk melayani Blazor skrip (_framework/blazor.*.js). Untuk informasi lebih lanjut, lihat file statis Blazor ASP.NET Core.

Untuk aplikasi Blazor WebAssembly dengan jalur URL relatif non-akar (misalnya, <base href="/CoolApp/">), aplikasi gagal menemukan sumber dayanya saat dijalankan secara lokal. Untuk mengatasi masalah ini selama pengembangan dan pengujian lokal, Anda dapat memberikan argumen jalur dasar yang cocok dengan nilai href dari tag <base> saat runtime. Jangan sertakan garis miring. Untuk meneruskan argumen dasar jalur saat menjalankan aplikasi secara lokal, jalankan perintah dotnet run dari direktori aplikasi dengan opsi --pathbase:

dotnet run --pathbase=/{RELATIVE URL PATH (no trailing slash)}

Untuk aplikasi Blazor WebAssembly dengan jalur URL relatif /CoolApp/ (<base href="/CoolApp/">), perintahnya adalah:

dotnet run --pathbase=/CoolApp

Jika Anda lebih suka mengonfigurasi profil peluncuran aplikasi untuk menentukan pathbase secara otomatis, bukan manual dengan dotnet run, atur properti commandLineArgs di Properties/launchSettings.json. Berikut ini juga mengonfigurasi URL peluncuran (launchUrl):

"commandLineArgs": "--pathbase=/{RELATIVE URL PATH (no trailing slash)}",
"launchUrl": "{RELATIVE URL PATH (no trailing slash)}",

Menggunakan CoolApp sebagai contoh:

"commandLineArgs": "--pathbase=/CoolApp",
"launchUrl": "CoolApp",

Menggunakan dotnet run dengan opsi --pathbase atau konfigurasi profil peluncuran yang menetapkan jalur dasar, aplikasi Blazor WebAssembly merespons secara lokal di http://localhost:port/CoolApp.

Untuk informasi selengkapnya tentang launchSettings.json file, lihat Menggunakan beberapa lingkungan di ASP.NET Core. Untuk informasi tambahan tentang Blazor jalur dan hosting dasar aplikasi, lihat <base href="/" /> atau alternatif tag dasar untuk Blazor integrasi MVC (dotnet/aspnetcore #43191).

Mendapatkan jalur dasar aplikasi dari konfigurasi

Panduan berikut menjelaskan cara mendapatkan jalur untuk <base> tag dari file pengaturan aplikasi untuk lingkungan yang berbeda.

Tambahkan file pengaturan aplikasi ke aplikasi. Contoh berikut adalah untuk Staging lingkungan (appsettings.Staging.json):

{
  "AppBasePath": "staging/"
}

Di aplikasi sisi Blazor server, muat jalur dasar dari konfigurasi dalam <head> konten:

@inject IConfiguration Config

...

<head>
    ...
    <base href="/@(Config.GetValue<string>("AppBasePath"))" />
    ...
</head>

Atau, aplikasi sisi server dapat memperoleh nilai dari konfigurasi untuk UsePathBase. Tempatkan kode berikut terlebih dahulu dalam alur pemrosesan permintaan aplikasi (Program.cs) segera setelah WebApplicationBuilder dibuat (builder.Build()). Contoh berikut menggunakan kunci AppBasePathkonfigurasi :

app.UsePathBase($"/{app.Configuration.GetValue<string>("AppBasePath")}");

Di aplikasi sisi Blazor WebAssembly klien:

• <base> Hapus tag dari wwwroot/index.html:

  - <base href="..." />
  

• Berikan jalur dasar aplikasi melalui HeadContent komponen dalam App komponen (App.razor):

  @inject IConfiguration Config
  
  ...
  
  <HeadContent>
      <base href="/@(Config.GetValue<string>("AppBasePath"))" />
  </HeadContent>
  

Jika tidak ada nilai konfigurasi untuk dimuat, misalnya di lingkungan non-penahapan, yang sebelumnya href diselesaikan ke jalur /akar .

Contoh di bagian ini berfokus pada penyediaan jalur dasar aplikasi dari pengaturan aplikasi, tetapi pendekatan membaca jalur dari IConfiguration berlaku untuk penyedia konfigurasi apa pun. Untuk informasi selengkapnya, lihat sumber daya berikut:

• Konfigurasi ASP.NET Core Blazor
• Konfigurasi di ASP.NET Core

Blazor ServerMapFallbackToPage konfigurasi

Bagian ini hanya berlaku untuk Blazor Server aplikasi. MapFallbackToPage tidak didukung di Blazor Web Apps dan Blazor WebAssembly aplikasi.

Dalam skenario di mana aplikasi memerlukan area terpisah dengan sumber daya kustom dan komponen Razor:

• Buat folder di dalam folder Pages aplikasi untuk menyimpan sumber daya. Misalnya, bagian administrator aplikasi dibuat di folder baru bernama Admin (Pages/Admin).

• Buat halaman akar (_Host.cshtml) untuk area tersebut. Misalnya, buat file Pages/Admin/_Host.cshtml dari halaman akar utama aplikasi (Pages/_Host.cshtml). Jangan berikan arahan @page di halaman Admin _Host.

• Tambahkan tata letak ke folder area (misalnya, Pages/Admin/_Layout.razor). Di tata letak untuk area terpisah, atur tag <base>href agar sesuai dengan folder area (misalnya, <base href="/Admin/" />). Untuk tujuan demonstrasi, tambahkan ~/ ke sumber daya statis di halaman. Contohnya:

  • ~/css/bootstrap/bootstrap.min.css
  • ~/css/site.css
  • ~/BlazorSample.styles.css (namespace aplikasi contoh adalah BlazorSample)
  • ~/_framework/blazor.server.js (skrip Blazor)

• Jika area tersebut harus memiliki folder aset statisnya sendiri, tambahkan folder tersebut dan tentukan lokasinya ke Middleware File Statis di Program.cs (misalnya, app.UseStaticFiles("/Admin/wwwroot")).

• Komponen Razor ditambahkan ke folder area. Minimal, tambahkan komponen Index ke folder area dengan arahan @page yang benar untuk area tersebut. Misalnya, tambahkan file Pages/Admin/Index.razor berdasarkan file Pages/Index.razor default aplikasi. Tunjukkan area Admin sebagai template rute di bagian atas file (@page "/admin"). Tambahkan komponen tambahan sesuai kebutuhan. Misalnya, Pages/Admin/Component1.razor dengan @page direktif dan template rute @page "/admin/component1.

• Di Program.cs, panggil MapFallbackToPage untuk jalur permintaan area tepat sebelum jalur halaman akar cadangan ke halaman _Host:

  ...
  app.UseRouting();
  
  app.MapBlazorHub();
  app.MapFallbackToPage("~/Admin/{*clientroutes:nonfile}", "/Admin/_Host");
  app.MapFallbackToPage("/_Host");
  
  app.Run();
  

Penyebaran

Untuk panduan penyebaran, lihat topik berikut:

• Menghosting dan menyebarkan ASP.NET Core Blazor WebAssembly
• Menghosting dan menyebarkan aplikasi sisi Blazor server ASP.NET Core