Konfigurasi ASP.NET Core Blazor

Artikel ini menjelaskan cara mengonfigurasi Blazor aplikasi, termasuk pengaturan aplikasi, autentikasi, dan konfigurasi pengelogan.

Panduan ini berlaku untuk konfigurasi proyek sisi klien di Blazor Aplikasi Web atau aplikasi mandiri Blazor WebAssembly .

Di Blazor Web Apps:

• Untuk konfigurasi sisi server:
  • Lihat Konfigurasi di ASP.NET Core untuk panduan.
  • Hanya konfigurasi dalam file pengaturan aplikasi akar proyek yang dimuat secara default.
  • Sisa artikel ini hanya berlaku untuk konfigurasi sisi klien dalam .Client proyek.
• Untuk konfigurasi sisi klien (.Client proyek), konfigurasi dimuat dari file pengaturan aplikasi berikut secara default:
  • wwwroot/appsettings.json.
  • wwwroot/appsettings.{ENVIRONMENT}.json, di mana {ENVIRONMENT} tempat penampung adalah lingkungan runtime aplikasi.

Di aplikasi mandiri Blazor WebAssembly , konfigurasi dimuat dari file pengaturan aplikasi berikut secara default:

• wwwroot/appsettings.json.
• wwwroot/appsettings.{ENVIRONMENT}.json, di mana {ENVIRONMENT} tempat penampung adalah lingkungan runtime aplikasi.

Catatan

Konfigurasi pengelogan yang ditempatkan ke dalam file pengaturan aplikasi tidak dimuat wwwroot secara default. Untuk informasi selengkapnya, lihat bagian Konfigurasi pengelogan nanti di artikel ini.

Dalam beberapa skenario, seperti dengan layanan Azure, penting untuk menggunakan segmen nama file lingkungan yang sama persis dengan nama lingkungan. Misalnya, gunakan nama appsettings.Staging.json file dengan modal "S" untuk Staging lingkungan. Untuk konvensi yang direkomendasikan, lihat komentar pembuka lingkungan ASP.NET CoreBlazor.

Penyedia konfigurasi lain yang terdaftar oleh aplikasi juga dapat menyediakan konfigurasi, tetapi tidak semua fitur penyedia atau penyedia sesuai:

• Penyedia konfigurasi Azure Key Vault: Penyedia tidak didukung untuk identitas terkelola dan ID aplikasi (ID klien) dengan skenario rahasia klien. ID Aplikasi dengan rahasia klien tidak disarankan untuk aplikasi ASP.NET Core apa pun, terutama aplikasi sisi klien karena rahasia klien tidak dapat diamankan sisi klien untuk mengakses layanan Azure Key Vault.
• Penyedia konfigurasi Aplikasi Azure: Penyedia tidak sesuai untuk aplikasi sisi klien karena tidak berjalan di server di Azure.

Untuk informasi selengkapnya tentang penyedia konfigurasi, lihat Konfigurasi di ASP.NET Core.

Peringatan

File konfigurasi dan pengaturan di akar web (wwwroot folder) terlihat oleh pengguna di klien, dan pengguna dapat mengubah data. Jangan simpan rahasia aplikasi, kredensial, atau data sensitif lainnya dalam file akar web apa pun.

Konfigurasi pengaturan aplikasi

Konfigurasi dalam file pengaturan aplikasi dimuat secara default. Dalam contoh berikut, nilai konfigurasi UI disimpan dalam file pengaturan aplikasi dan dimuat oleh Blazor kerangka kerja secara otomatis. Nilai dibaca oleh komponen.

wwwroot/appsettings.json:

{
    "h1FontSize": "50px"
}

IConfiguration Masukkan instans ke dalam komponen untuk mengakses data konfigurasi.

ConfigExample.razor:

@page "/config-example"
@inject IConfiguration Configuration

<PageTitle>Configuration</PageTitle>

<h1 style="font-size:@Configuration["h1FontSize"]">
    Configuration example (50px)
</h1>

Pembatasan keamanan klien mencegah akses langsung ke file melalui kode pengguna, termasuk file pengaturan untuk konfigurasi aplikasi. Untuk membaca file konfigurasi selain appsettings.json/appsettings.{ENVIRONMENT}.json dari folder ke wwwroot dalam konfigurasi, gunakan .HttpClient

Peringatan

File konfigurasi dan pengaturan di akar web (wwwroot folder) terlihat oleh pengguna di klien, dan pengguna dapat mengubah data. Jangan simpan rahasia aplikasi, kredensial, atau data sensitif lainnya dalam file akar web apa pun.

Contoh berikut membaca file konfigurasi (cars.json) ke dalam konfigurasi aplikasi.

wwwroot/cars.json:

{
    "size": "tiny"
}

Tambahkan namespace layanan untuk Microsoft.Extensions.Configuration ke Program file:

using Microsoft.Extensions.Configuration;

Ubah pendaftaran layanan yang HttpClient ada untuk menggunakan klien untuk membaca file:

var http = new HttpClient()
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
};

builder.Services.AddScoped(sp => http);

using var response = await http.GetAsync("cars.json");
using var stream = await response.Content.ReadAsStreamAsync();

builder.Configuration.AddJsonStream(stream);

Contoh sebelumnya mengatur alamat dasar dengan builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), yang mendapatkan alamat dasar untuk aplikasi dan biasanya berasal dari <base> nilai tag href di halaman host.

Sumber Konfigurasi Memori

Contoh berikut menggunakan MemoryConfigurationSource dalam Program file untuk menyediakan konfigurasi tambahan.

Tambahkan namespace layanan untuk Microsoft.Extensions.Configuration.Memory ke Program file:

using Microsoft.Extensions.Configuration.Memory;

Dalam file Program:

var vehicleData = new Dictionary<string, string?>()
{
    { "color", "blue" },
    { "type", "car" },
    { "wheels:count", "3" },
    { "wheels:brand", "Blazin" },
    { "wheels:brand:type", "rally" },
    { "wheels:year", "2008" },
};

var memoryConfig = new MemoryConfigurationSource { InitialData = vehicleData };

builder.Configuration.Add(memoryConfig);

IConfiguration Masukkan instans ke dalam komponen untuk mengakses data konfigurasi.

MemoryConfig.razor:

@page "/memory-config"
@inject IConfiguration Configuration

<PageTitle>Memory Configuration</PageTitle>

<h1>Memory Configuration Example</h1>

<h2>General specifications</h2>

<ul>
    <li>Color: @Configuration["color"]</li>
    <li>Type: @Configuration["type"]</li>
</ul>

<h2>Wheels</h2>

<ul>
    <li>Count: @Configuration["wheels:count"]</li>
    <li>Brand: @Configuration["wheels:brand"]</li>
    <li>Type: @Configuration["wheels:brand:type"]</li>
    <li>Year: @Configuration["wheels:year"]</li>
</ul>

Dapatkan bagian konfigurasi dalam kode C# dengan IConfiguration.GetSection. Contoh berikut mendapatkan bagian wheels untuk konfigurasi dalam contoh sebelumnya:

@code {
    protected override void OnInitialized()
    {
        var wheelsSection = Configuration.GetSection("wheels");

        ...
    }
}

Konfigurasi autentikasi

Menyediakan konfigurasi autentikasi publik dalam file pengaturan aplikasi.

wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Muat konfigurasi untuk Identity penyedia dengan ConfigurationBinder.Bind dalam Program file. Contoh berikut memuat konfigurasi untuk penyedia OIDC:

builder.Services.AddOidcAuthentication(options =>
    builder.Configuration.Bind("Local", options.ProviderOptions));

Peringatan

File konfigurasi dan pengaturan di akar web (wwwroot folder) terlihat oleh pengguna di klien, dan pengguna dapat mengubah data. Jangan simpan rahasia aplikasi, kredensial, atau data sensitif lainnya dalam file akar web apa pun.

Konfigurasi pengelogan

Bagian ini berlaku untuk aplikasi yang mengonfigurasi pengelogan melalui file pengaturan aplikasi di wwwroot folder.

Microsoft.Extensions.Logging.Configuration Tambahkan paket ke aplikasi.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Dalam file pengaturan aplikasi, berikan konfigurasi pengelogan. Konfigurasi pengelogan dimuat dalam Program file.

wwwroot/appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Dalam file Program:

builder.Logging.AddConfiguration(
    builder.Configuration.GetSection("Logging"));

Konfigurasi penyusun host

Baca konfigurasi penyusun host dari WebAssemblyHostBuilder.Configuration dalam Program file:

var hostname = builder.Configuration["HostName"];

Konfigurasi cache

File konfigurasi di-cache untuk penggunaan offline. Dengan Progresif Web Applications (PWAs), Anda hanya dapat memperbarui file konfigurasi saat membuat penyebaran baru. Mengedit file konfigurasi antar penyebaran tidak berpengaruh karena:

• Pengguna memiliki versi cache file yang terus mereka gunakan.
• File dan service-worker-assets.js PWA service-worker.js harus dibangun kembali pada kompilasi, yang memberi sinyal ke aplikasi pada kunjungan online pengguna berikutnya bahwa aplikasi telah disebarkan ulang.

Untuk informasi selengkapnya tentang bagaimana pembaruan latar belakang ditangani oleh PWAs, lihat ASP.NET Core Blazor Progressive Web Application (PWA).

Konfigurasi opsi

Konfigurasi opsi memerlukan penambahan referensi paket untuk Microsoft.Extensions.Options.ConfigurationExtensions paket NuGet.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Contoh:

builder.Services.Configure<MyOptions>(
    builder.Configuration.GetSection("MyOptions"));

Tidak semua fitur ASP.NET Core Options didukung dalam Razor komponen. Misalnya, IOptionsSnapshot<TOptions> dan IOptionsMonitor<TOptions> konfigurasi didukung, tetapi nilai opsi komputasi ulang untuk antarmuka ini tidak didukung di luar pemuatan ulang aplikasi dengan meminta aplikasi di tab browser baru atau memilih tombol muat ulang browser. Hanya memanggil StateHasChanged tidak memperbarui rekam jepret atau nilai opsi yang dipantau saat konfigurasi yang mendasar berubah.