Bagikan melalui

file statis ASP.NET Core Blazor

  • Artikel

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 Blazor konfigurasi aplikasi untuk menyajikan file statis.

Middleware aset statis

Bagian ini berlaku untuk aplikasi sisi Blazor server.

Melayani aset statis dikelola oleh salah satu dari dua middleware yang dijelaskan dalam tabel berikut.

Middleware API Versi .NET Deskripsi
Petakan Aset Statis MapStaticAssets .NET 9 atau yang lebih baru Mengoptimalkan pengiriman aset statis kepada klien.
File Statis UseStaticFiles Semua versi .NET Melayani aset statis kepada klien tanpa pengoptimalan MapStaticAssets tetapi berguna untuk beberapa tugas yang MapStaticAssets tidak mampu mengelola.

Konfigurasikan Middleware Aset Statis Peta dengan memanggil MapStaticAssets dalam alur pemrosesan permintaan aplikasi, yang melakukan hal berikut:

MapStaticAssets beroperasi dengan menggabungkan proses build dan publish untuk mengumpulkan informasi tentang aset statis di aplikasi. Informasi ini digunakan oleh pustaka runtime untuk melayani aset statis secara efisien ke browser.

MapStaticAssets dapat menggantikan UseStaticFiles dalam sebagian besar situasi. Namun, MapStaticAssets dioptimalkan untuk melayani aset dari lokasi yang diketahui di aplikasi pada waktu build dan penerbitan. Jika aplikasi melayani aset dari lokasi lain, seperti disk atau sumber daya yang disematkan, UseStaticFiles harus digunakan.

MapStaticAssets menggantikan panggilan UseBlazorFrameworkFiles dalam aplikasi yang melayani Blazor WebAssembly file kerangka kerja, dan secara eksplisit memanggil UseBlazorFrameworkFiles dalam Blazor Web App tidak diperlukan karena API secara otomatis dipanggil saat memanggil AddInteractiveWebAssemblyComponents.

MapStaticAssets memberikan manfaat berikut yang tidak tersedia saat memanggil UseStaticFiles:

  • Kompresi build-time untuk semua aset di aplikasi, termasuk JavaScript (JS) dan lembar gaya tetapi tidak termasuk aset gambar dan font yang sudah dikompresi. Kompresi Gzip (Content-Encoding: gz) digunakan selama pengembangan. Gzip dengan kompresi Brotli (Content-Encoding: br) digunakan selama penerbitan.
  • Sidik jari untuk semua aset pada waktu build dengan string yang dikodekan Base64 dari hash SHA-256 dari konten setiap file. Ini mencegah penggunaan kembali versi lama file, bahkan jika file lama di-cache. Aset sidik jari di-cache menggunakan immutable direktif, yang mengakibatkan browser tidak pernah meminta aset lagi sampai berubah. Untuk browser yang tidak mendukung arahanimmutable, arahan max-age ditambahkan.
    • Bahkan jika aset tidak disidik jari, berbasis ETags konten dihasilkan untuk setiap aset statis menggunakan hash sidik jari file sebagai ETag nilai . Ini memastikan bahwa browser hanya mengunduh file jika kontennya berubah (atau file sedang diunduh untuk pertama kalinya).
    • Secara internal, Blazor memetakan aset fisik ke sidik jari mereka, yang memungkinkan aplikasi untuk:
      • Temukan aset yang dihasilkan Blazor secara otomatis, seperti Razor CSS yang dilingkup komponen untuk Blazorfitur isolasi CSS , dan JS aset yang dijelaskan oleh JS peta impor.
      • Buat tag tautan di <head> konten halaman untuk memuat aset sebelumnya.
  • Selama pengujian pengembangan Visual Studio Hot Reload :
    • Informasi integritas dihapus dari aset untuk menghindari masalah saat file diubah saat aplikasi sedang berjalan.
    • Aset statis tidak di-cache untuk memastikan bahwa browser selalu mengambil konten saat ini.

Saat mode render Interactive WebAssembly atau Interactive Auto diaktifkan:

  • Blazor membuat titik akhir untuk mengekspos koleksi sumber daya sebagai JS modul.
  • URL dipancarkan ke isi permintaan sebagai status komponen yang bertahan ketika komponen WebAssembly dirender ke halaman.
  • Selama boot WebAssembly, Blazor mengambil URL, mengimpor modul, dan memanggil fungsi untuk mengambil koleksi aset dan membangunnya kembali dalam memori. URL khusus untuk konten dan di-cache selamanya, sehingga biaya overhead ini hanya dibayar sekali per pengguna sampai aplikasi diperbarui.
  • Koleksi sumber daya juga diekspos pada URL yang dapat dibaca manusia (_framework/resource-collection.js), sehingga JS memiliki akses ke koleksi sumber daya untuk navigasi yang ditingkatkan atau untuk mengimplementasikan fitur kerangka kerja lain dan komponen pihak ketiga.

Middleware Aset Statis Peta tidak menyediakan fitur untuk minifikasi atau transformasi file lainnya. Minifikasi biasanya ditangani oleh kode kustom atau alat pihak ketiga.

Middleware File Statis (UseStaticFiles) berguna dalam situasi berikut yang MapStaticAssets tidak dapat menangani:

Mengonsumsi aset dengan Middleware File Statis Peta

Bagian ini berlaku untuk aplikasi sisi Blazor server.

Aset digunakan melalui ComponentBase.Assets properti , yang menyelesaikan URL sidik jari untuk aset tertentu. Dalam contoh berikut, Bootstrap, Blazor lembar gaya aplikasi templat proyek (app.css), dan lembar gaya isolasi CSS ditautkan dalam komponen akar, biasanya App komponen (Components/App.razor):

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorWeb-CSharp.styles.css"]" />

Mengimpor peta

Bagian ini berlaku untuk aplikasi sisi Blazor server.

Komponen ImportMap mewakili elemen peta impor (<script type="importmap"></script>) yang menentukan peta impor untuk skrip modul. Komponen ImportMap ditempatkan dalam <head> konten komponen akar, biasanya App komponen (Components/App.razor).

<ImportMap />

Jika kustom ImportMapDefinition tidak ditetapkan ke ImportMap komponen, peta impor dihasilkan berdasarkan aset aplikasi.

Contoh berikut menunjukkan definisi peta impor kustom dan peta impor yang mereka buat.

Peta impor dasar:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

Kode sebelumnya menghasilkan peta impor berikut:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Peta impor terlingkup:

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

Kode sebelumnya menghasilkan peta impor berikut:

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Impor peta dengan integritas:

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

Kode sebelumnya menghasilkan peta impor berikut:

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Gabungkan definisi peta impor (ImportMapDefinition) dengan ImportMapDefinition.Combine.

Impor peta yang ResourceAssetCollection dibuat dari yang memetakan aset statis ke URL unik yang sesuai:

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

Kode sebelumnya menghasilkan peta impor berikut:

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

Konfigurasikan Middleware File Statis untuk melayani aset statis kepada klien dengan memanggil UseStaticFiles dalam alur pemrosesan permintaan aplikasi. Untuk informasi selengkapnya, lihat File statis di ASP.NET Core.

Dalam rilis sebelum .NET 8, Blazor file statis kerangka kerja, seperti Blazor skrip, disajikan melalui Middleware File Statis. Di .NET 8 atau yang lebih baru, Blazor file statis kerangka kerja dipetakan menggunakan perutean titik akhir, dan Middleware File Statis tidak lagi digunakan.

Bagian ini berlaku untuk semua rilis dan Blazor aplikasi .NET.

Tabel berikut ini meringkas format file <link> href statis menurut rilis .NET.

Untuk lokasi <head> konten tempat tautan file statis ditempatkan, lihat struktur proyek ASP.NET CoreBlazor. Tautan aset statis juga dapat disediakan menggunakan <HeadContent> komponen dalam komponen individual Razor .

Untuk lokasi <head> konten tempat tautan file statis ditempatkan, lihat struktur proyek ASP.NET CoreBlazor.

.NET 9 atau yang lebih baru

Jenis aplikasi href nilai Contoh
Blazor Web App @Assets["{PATH}"] <link rel="stylesheet" href="@Assets["app.css"]" />
<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor Server† @Assets["{PATH}"] <link href="@Assets["css/site.css"]" rel="stylesheet" />
<link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Mandiri Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Jenis aplikasi href nilai Contoh
Blazor Web App {PATH} <link rel="stylesheet" href="app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor Server† {PATH} <link href="css/site.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Mandiri Blazor WebAssembly {PATH} <link rel="stylesheet" href="css/app.css" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x atau yang lebih lama

Jenis aplikasi href nilai Contoh
Blazor Server† {PATH} <link href="css/site.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Dihosting Blazor WebAssembly‡ {PATH} <link href="css/app.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly {PATH} <link href="css/app.css" rel="stylesheet" />
<link href="_content/ComponentLib/styles.css" rel="stylesheet" />

Blazor Server† didukung di .NET 8 atau yang lebih baru tetapi bukan lagi templat proyek setelah .NET 7.
‡Sebaiknya perbarui aplikasi yang dihosting Blazor WebAssembly ke Blazor Web Apps saat mengadopsi .NET 8 atau yang lebih baru.

Mode Proyek Aset Web Statis

Bagian ini berlaku untuk .Client proyek .Blazor Web App

Pengaturan yang Blazor Web App diperlukan <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> dalam .Client proyek mengembalikan Blazor WebAssembly perilaku aset statis kembali ke default, sehingga proyek berulah sebagai bagian dari proyek yang dihosting. Blazor WebAssembly SDK (Microsoft.NET.Sdk.BlazorWebAssembly) mengonfigurasi aset web statis dengan cara tertentu untuk bekerja dalam mode "mandiri" dengan server hanya menggunakan output dari pustaka. Ini tidak sesuai untuk Blazor Web App, di mana bagian WebAssembly dari aplikasi adalah bagian logis dari host dan harus bereaksi lebih seperti pustaka. Misalnya, proyek tidak mengekspos bundel gaya (misalnya, BlazorSample.Client.styles.css) dan sebaliknya hanya menyediakan host dengan bundel proyek, sehingga host dapat menyertakannya dalam bundel gayanya sendiri.

Mengubah nilai (Default) <StaticWebAssetProjectMode> atau menghapus properti dari .Client proyek tidak didukung.

File statis di lingkungan non-Development

Bagian ini berlaku untuk file statis sisi server.

Saat menjalankan aplikasi secara lokal, aset web statis hanya diaktifkan di Development lingkungan. Untuk mengaktifkan file statis untuk lingkungan selain Development selama pengembangan dan pengujian lokal (misalnya, Staging), panggil UseStaticWebAssets di WebApplicationBuilder dalam Program file.

Peringatan

Panggil UseStaticWebAssets lingkungan yang tepat untuk mencegah mengaktifkan fitur dalam produksi, karena melayani file dari lokasi terpisah pada disk selain dari proyek jika dipanggil di lingkungan produksi. Contoh di bagian ini memeriksa Staging lingkungan dengan memanggil IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Awalan untuk Blazor WebAssembly aset

Bagian ini berlaku untuk Blazor Web Apps.

WebAssemblyComponentsEndpointOptions.PathPrefix Gunakan opsi titik akhir untuk mengatur string jalur yang menunjukkan awalan untuk Blazor WebAssembly aset. Jalur harus sesuai dengan proyek aplikasi yang dirujuk Blazor WebAssembly .

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

Dalam contoh sebelumnya, {PATH PREFIX} tempat penampung adalah awalan jalur dan harus dimulai dengan garis miring (/).

Dalam contoh berikut, awalan jalur diatur ke /path-prefix:

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Jalur dasar aset web statis

Bagian ini berlaku untuk aplikasi mandiri Blazor WebAssembly .

Menerbitkan aplikasi menempatkan aset statis aplikasi, termasuk Blazor file kerangka kerja (_framework aset folder), di jalur akar (/) dalam output yang diterbitkan. <StaticWebAssetBasePath> Properti yang ditentukan dalam file proyek (.csproj) mengatur jalur dasar ke jalur non-akar:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Dalam contoh sebelumnya, {PATH} tempat penampung adalah jalurnya.

Tanpa mengatur <StaticWebAssetBasePath> properti, aplikasi mandiri diterbitkan di /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

Dalam contoh sebelumnya, {TFM} tempat penampung adalah Target Framework Moniker (TFM) (misalnya, net6.0).

<StaticWebAssetBasePath> Jika properti dalam aplikasi mandiri Blazor WebAssembly mengatur jalur aset statis yang diterbitkan ke app1, jalur akar ke aplikasi dalam output yang diterbitkan adalah /app1.

Dalam file proyek aplikasi mandiri Blazor WebAssembly (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Dalam output yang diterbitkan, jalur ke aplikasi mandiri Blazor WebAssembly adalah /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

Dalam contoh sebelumnya, {TFM} tempat penampung adalah Target Framework Moniker (TFM) (misalnya, net6.0).

Bagian ini berlaku untuk aplikasi mandiri Blazor WebAssembly dan solusi yang dihosting Blazor WebAssembly .

Menerbitkan aplikasi menempatkan aset statis aplikasi, termasuk Blazor file kerangka kerja (_framework aset folder), di jalur akar (/) dalam output yang diterbitkan. <StaticWebAssetBasePath> Properti yang ditentukan dalam file proyek (.csproj) mengatur jalur dasar ke jalur non-akar:

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Dalam contoh sebelumnya, {PATH} tempat penampung adalah jalurnya.

Tanpa mengatur <StaticWebAssetBasePath> properti, aplikasi klien solusi yang dihosting atau aplikasi mandiri diterbitkan di jalur berikut:

  • Server Dalam proyek solusi yang dihostingBlazor WebAssembly:/BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • Di aplikasi mandiri Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

<StaticWebAssetBasePath> Jika properti dalam proyek aplikasi yang dihosting Blazor WebAssembly Client atau di aplikasi mandiri Blazor WebAssembly mengatur jalur aset statis yang diterbitkan ke app1, jalur akar ke aplikasi dalam output yang diterbitkan adalah /app1.

Client Dalam file proyek aplikasi (.csproj) atau file proyek aplikasi mandiri Blazor WebAssembly (.csproj):

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Dalam output yang diterbitkan:

  • Jalur ke aplikasi klien dalam proyek solusi yang dihosting Server Blazor WebAssembly : /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Jalur ke aplikasi mandiri Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

Properti <StaticWebAssetBasePath> ini paling umum digunakan untuk mengontrol jalur ke aset statis yang diterbitkan dari beberapa Blazor WebAssembly aplikasi dalam satu penyebaran yang dihosting. Untuk informasi selengkapnya, lihat Beberapa aplikasi ASP.NET Core Blazor WebAssembly yang dihosting. Properti ini juga efektif dalam aplikasi mandiri Blazor WebAssembly .

Dalam contoh sebelumnya, {TFM} tempat penampung adalah Target Framework Moniker (TFM) (misalnya, net6.0).

Pemetaan file dan opsi file statis

Bagian ini berlaku untuk file statis sisi server.

Untuk membuat pemetaan file tambahan dengan FileExtensionContentTypeProvider atau mengonfigurasi yang lain StaticFileOptions, gunakan salah satu pendekatan berikut. Dalam contoh berikut, {EXTENSION} tempat penampung adalah ekstensi file, dan {CONTENT TYPE} tempat penampung adalah jenis konten. Namespace untuk API berikut adalah Microsoft.AspNetCore.StaticFiles.

  • Konfigurasikan opsi melalui injeksi dependensi (DI) dalam Program file menggunakan StaticFileOptions:

    var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

app.UseStaticFiles();

  • Teruskan StaticFileOptions langsung ke UseStaticFiles Program dalam file:

    var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });

Untuk membuat pemetaan file tambahan dengan FileExtensionContentTypeProvider atau mengonfigurasi yang lain StaticFileOptions, gunakan salah satu pendekatan berikut. Dalam contoh berikut, {EXTENSION} tempat penampung adalah ekstensi file, dan {CONTENT TYPE} tempat penampung adalah jenis konten.

  • Konfigurasikan opsi melalui injeksi dependensi (DI) dalam Program file menggunakan StaticFileOptions:

    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Pendekatan ini mengonfigurasi penyedia file yang sama yang digunakan untuk melayani Blazor skrip. Pastikan konfigurasi kustom Anda tidak mengganggu penyajian Blazor skrip. Misalnya, jangan hapus pemetaan untuk file JavaScript dengan mengonfigurasi penyedia dengan provider.Mappings.Remove(".js").

  • Gunakan dua panggilan ke UseStaticFiles Program dalam file:

    • Konfigurasikan penyedia file kustom dalam panggilan pertama dengan StaticFileOptions.
    • Middleware kedua melayani Blazor skrip, yang menggunakan konfigurasi file statis default yang disediakan oleh Blazor kerangka kerja.
    using Microsoft.AspNetCore.StaticFiles;

...

var provider = new FileExtensionContentTypeProvider();
provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

  • Anda dapat menghindari mengganggu penyajian _framework/blazor.server.js dengan menggunakan MapWhen untuk menjalankan Middleware File Statis kustom:

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

Menyajikan file dari beberapa lokasi

Panduan di bagian ini hanya berlaku untuk Blazor Web Apps.

Untuk menyajikan file dari beberapa lokasi dengan CompositeFileProvider:

Contoh:

Buat folder baru di proyek server bernama AdditionalStaticAssets. Tempatkan gambar ke dalam folder.

Tambahkan pernyataan berikut using ke bagian atas file proyek Program server:

using Microsoft.Extensions.FileProviders;

Dalam file proyek server sebelum panggilan ke UseStaticFiles, tambahkan kode berikut:Program

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Dalam markup komponen aplikasi Home (Home.razor), referensikan gambar dengan <img> tag:

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

Dalam contoh sebelumnya:

  • Tempat {IMAGE FILE NAME} penampung adalah nama file gambar. Tidak perlu menyediakan segmen jalur jika file gambar berada di akar AdditionalStaticAssets folder.
  • Tempat {ALT TEXT} penampung adalah teks alternatif gambar.

Jalankan aplikasi.

Sumber Daya Tambahan: