lingkungan ASP.NET Core Blazor

Artikel ini menjelaskan cara mengonfigurasi dan membaca lingkungan dalam aplikasi Blazor .

Saat menjalankan aplikasi secara lokal, lingkungan default ke Development. Saat aplikasi diterbitkan, lingkungan default ke Production.

Kami merekomendasikan konvensi berikut:

• Selalu gunakan nama lingkungan "Development" untuk pengembangan lokal. Ini karena kerangka kerja ASP.NET Core mengharapkan nama tersebut persis saat mengonfigurasi aplikasi dan alat untuk eksekusi pengembangan lokal aplikasi.

• Untuk lingkungan pengujian, penahapan, dan produksi, selalu terbitkan dan sebarkan aplikasi. Anda dapat menggunakan skema penamaan lingkungan apa pun yang Anda inginkan untuk aplikasi yang diterbitkan, tetapi selalu gunakan nama file pengaturan aplikasi dengan casing segmen lingkungan yang sama persis dengan nama lingkungan. Untuk penahapan, gunakan "Staging" (modal "S") sebagai nama lingkungan, dan beri nama file pengaturan aplikasi agar cocok (appsettings.Staging.json). Untuk produksi, gunakan "Production" (modal "P") sebagai nama lingkungan, dan beri nama file pengaturan aplikasi yang cocok (appsettings.Production.json).

Mengatur lingkungan

Lingkungan diatur menggunakan salah satu pendekatan berikut:

• Blazor Web App: Gunakan salah satu pendekatan yang dijelaskan dalam Menggunakan beberapa lingkungan di ASP.NET Core untuk aplikasi umum ASP.NET Core.
• Blazor Web App atau mandiri Blazor WebAssembly: Blazor mulai konfigurasi
• Blazor WebAssemblyMandiri : blazor-environment header
• Blazor Web App atau mandiri Blazor WebAssembly: Azure App Service

Pada klien untuk Blazor Web App, lingkungan ditentukan dari server melalui middleware yang mengomunikasikan lingkungan ke browser melalui header bernama blazor-environment. Header mengatur lingkungan saat WebAssemblyHost dibuat dalam file sisi Program klien (WebAssemblyHostBuilder.CreateDefault).

Untuk aplikasi mandiri Blazor WebAssembly yang berjalan secara lokal, server pengembangan menambahkan blazor-environment header.

Untuk aplikasi yang berjalan secara lokal dalam pengembangan, aplikasi default ke Development lingkungan. Menerbitkan aplikasi secara default lingkungan ke Production.

Mengatur lingkungan sisi klien melalui Blazor konfigurasi startup

Contoh berikut dimulai Blazor di Staging lingkungan jika nama host menyertakan localhost. Jika tidak, lingkungan diatur ke nilai defaultnya.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      webAssembly: {
        environment: "Staging"
      }
    });
  } else {
    Blazor.start();
  }
</script>

Dalam contoh sebelumnya, {BLAZOR SCRIPT} tempat penampung adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat struktur proyek ASP.NET CoreBlazor.

Catatan

Untuk Blazor Web Appitu, atur webAssembly>environment properti dalam Blazor.start konfigurasi, sangat bijaksana untuk mencocokkan lingkungan sisi server dengan lingkungan yang diatur pada environment properti . Jika tidak, pra-penyajian di server akan beroperasi di bawah lingkungan yang berbeda dari penyajian pada klien, yang menghasilkan efek semena-mena. Untuk panduan umum tentang mengatur lingkungan untuk Blazor Web App, lihat Menggunakan beberapa lingkungan di ASP.NET Core.

Mandiri Blazor WebAssembly:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  if (window.location.hostname.includes("localhost")) {
    Blazor.start({
      environment: "Staging"
    });
  } else {
    Blazor.start();
  }
</script>

Dalam contoh sebelumnya, {BLAZOR SCRIPT} tempat penampung adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat struktur proyek ASP.NET CoreBlazor.

environment Menggunakan properti akan mengambil alih lingkungan yang diatur oleh blazor-environment header.

Pendekatan sebelumnya mengatur lingkungan klien tanpa mengubah blazor-environment nilai header, juga tidak mengubah pengelogan konsol proyek server dari lingkungan startup untuk Blazor Web App yang telah mengadopsi rendering WebAssembly Interaktif global.

Untuk mencatat lingkungan ke konsol dalam proyek mandiri atau proyek , tempatkan kode C# berikut dalam Program file setelah WebAssemblyHost dibuat dengan WebAssemblyHostBuilder.CreateDefault dan sebelum baris yang membangun dan menjalankan proyek (await builder.Build().RunAsync();):Blazor Web App.Client Blazor WebAssembly

Console.WriteLine(
    $"Client Hosting Environment: {builder.HostEnvironment.Environment}");

Untuk informasi lebih lanjut tentang startup Blazor, lihat startup BlazorASP.NET Core.

Mengatur lingkungan sisi klien melalui header

Blazor WebAssembly aplikasi dapat mengatur lingkungan dengan blazor-environment header.

Dalam contoh berikut untuk IIS, header kustom (blazor-environment) ditambahkan ke file yang diterbitkan web.config . File web.config terletak di bin/Release/{TARGET FRAMEWORK}/publish folder , di mana {TARGET FRAMEWORK} tempat penampung adalah kerangka kerja target:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>

    ...

    <httpProtocol>
      <customHeaders>
        <add name="blazor-environment" value="Staging" />
      </customHeaders>
    </httpProtocol>
  </system.webServer>
</configuration>

Catatan

Untuk menggunakan file kustom web.config untuk IIS yang tidak ditimpa saat aplikasi diterbitkan ke publish folder, lihat Host dan sebarkan ASP.NET Core Blazor WebAssembly.

Blazor Meskipun kerangka kerja mengeluarkan nama header di semua huruf kecil (blazor-environment), Anda dipersilakan untuk menggunakan casing apa pun yang Anda inginkan. Misalnya, nama header yang memanfaatkan setiap kata (Blazor-Environment) didukung.

Mengatur lingkungan untuk Azure App Service

Untuk aplikasi mandiri Blazor WebAssembly , Anda dapat mengatur lingkungan secara manual melalui konfigurasi mulai atau blazor-environment header.

Untuk aplikasi sisi server, atur lingkungan melalui ASPNETCORE_ENVIRONMENT pengaturan aplikasi di Azure:

1. Konfirmasikan bahwa casing segmen lingkungan dalam nama file pengaturan aplikasi cocok dengan casing nama lingkungan mereka dengan tepat. Misalnya, nama file pengaturan aplikasi yang cocok untuk Staging lingkungan adalah appsettings.Staging.json. Jika nama file adalah appsettings.staging.json (huruf kecil "s"), file tidak berada, dan pengaturan dalam file tidak digunakan di Staging lingkungan.

2. Untuk penyebaran Visual Studio, konfirmasikan bahwa aplikasi disebarkan ke slot penyebaran yang benar. Untuk aplikasi bernama BlazorAzureAppSample, aplikasi disebarkan ke Staging slot penyebaran.

3. Di portal Azure untuk slot penyebaran lingkungan, atur lingkungan dengan ASPNETCORE_ENVIRONMENT pengaturan aplikasi. Untuk aplikasi bernama BlazorAzureAppSample, Slot App Service penahapan diberi nama BlazorAzureAppSample/Staging. Staging Untuk konfigurasi slot, buat pengaturan aplikasi untuk ASPNETCORE_ENVIRONMENT dengan nilai Staging. Pengaturan slot penyebaran diaktifkan untuk pengaturan.

Saat diminta di browser, BlazorAzureAppSample/Staging aplikasi dimuat di Staging lingkungan di https://blazorazureappsample-staging.azurewebsites.net.

Saat aplikasi dimuat di browser, kumpulan header respons untuk blazor.boot.json menunjukkan bahwa blazor-environment nilai header adalah Staging.

Pengaturan aplikasi dari appsettings.{ENVIRONMENT}.json file dimuat oleh aplikasi, di mana {ENVIRONMENT} tempat penampung adalah lingkungan aplikasi. Dalam contoh sebelumnya, pengaturan dari file dimuat appsettings.Staging.json .

Membaca lingkungan di Blazor WebAssembly aplikasi

Dapatkan lingkungan aplikasi dalam komponen dengan menyuntikkan IWebAssemblyHostEnvironment dan membaca Environment properti .

ReadEnvironment.razor:

@page "/read-environment"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IWebAssemblyHostEnvironment Env

<h1>Environment example</h1>

<p>Environment: @Env.Environment</p>

Membaca sisi klien lingkungan dalam Blazor Web App

Dengan asumsi bahwa pra-penyajian tidak dinonaktifkan untuk komponen atau aplikasi, komponen dalam .Client proyek telah dirender di server. Karena server tidak memiliki layanan terdaftar, tidak dimungkinkan untuk menyuntikkan IWebAssemblyHostEnvironment layanan dan menggunakan metode dan properti ekstensi lingkungan host implementasi layanan selama prarendering server. Menyuntikkan layanan ke komponen Interactive WebAssembly atau Interactive Auto menghasilkan kesalahan runtime berikut:

There is no registered service of type 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment'.

Untuk mengatasi hal ini, buat implementasi layanan kustom untuk IWebAssemblyHostEnvironment di server. Tambahkan kelas berikut ke proyek server.

ServerHostEnvironment.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using Microsoft.AspNetCore.Components;

public class ServerHostEnvironment(IWebHostEnvironment env, NavigationManager nav) : 
    IWebAssemblyHostEnvironment
{
    public string Environment => env.EnvironmentName;
    public string BaseAddress => nav.BaseUri;
}

Dalam file proyek Program server, daftarkan layanan:

builder.Services.TryAddScoped<IWebAssemblyHostEnvironment, ServerHostEnvironment>();

Pada titik ini, IWebAssemblyHostEnvironment layanan dapat disuntikkan ke komponen WebAssembly interaktif atau Interaktif Otomatis dan digunakan seperti yang ditunjukkan di bagian Baca lingkungan di Blazor WebAssembly aplikasi .

Contoh sebelumnya dapat menunjukkan bahwa dimungkinkan untuk memiliki lingkungan server yang berbeda dari lingkungan klien, yang tidak direkomendasikan dan dapat menyebabkan hasil arbitrer. Saat mengatur lingkungan dalam Blazor Web App, yang terbaik adalah mencocokkan lingkungan server dan .Client proyek. Pertimbangkan skenario berikut dalam aplikasi pengujian:

• Terapkan properti lingkungan sisi klien (webassembly) dengan Staging lingkungan melalui Blazor.start. Lihat bagian Atur lingkungan sisi klien melalui konfigurasi startup misalnya.
• Jangan ubah file sisi Properties/launchSettings.json server. Biarkan bagian environmentVariables dengan ASPNETCORE_ENVIRONMENT variabel lingkungan diatur ke Development.

Anda dapat melihat nilai IWebAssemblyHostEnvironment.Environment perubahan properti di UI.

Saat pra-penyajian terjadi di server, komponen dirender di Development lingkungan:

Environment: Development

Ketika komponen dirender hanya satu atau dua detik kemudian, setelah Blazor bundel diunduh dan runtime .NET WebAssembly diaktifkan, nilai berubah untuk mencerminkan bahwa klien beroperasi di Staging lingkungan pada klien:

Environment: Staging

Contoh sebelumnya menunjukkan mengapa kami merekomendasikan pengaturan lingkungan server agar sesuai dengan lingkungan klien untuk pengembangan, pengujian, dan penyebaran produksi.

Untuk informasi selengkapnya, lihat bagian Layanan sisi klien gagal diselesaikan selama pra-penyajian dari artikel Mode render, yang muncul nanti dalam Blazor dokumentasi.

Membaca lingkungan sisi klien selama startup

Selama startup, WebAssemblyHostBuilder mengekspos IWebAssemblyHostEnvironment melalui HostEnvironment properti , yang memungkinkan logika khusus lingkungan dalam kode pembangun host.

Dalam file Program:

if (builder.HostEnvironment.Environment == "Custom")
{
    ...
};

Metode ekstensi kenyamanan berikut yang disediakan melalui WebAssemblyHostEnvironmentExtensions izin memeriksa lingkungan saat ini untuk Development, Production, Staging, dan nama lingkungan kustom:

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Dalam file Program:

if (builder.HostEnvironment.IsStaging())
{
    ...
};

if (builder.HostEnvironment.IsEnvironment("Custom"))
{
    ...
};

Properti IWebAssemblyHostEnvironment.BaseAddress dapat digunakan selama startup saat NavigationManager layanan tidak tersedia.

Sumber Daya Tambahan:

• startup ASP.NET Core Blazor
• Gunakan beberapa lingkungan di ASP.NET Core
• Blazorsampel repositori GitHub () (dotnet/blazor-samplescara mengunduh)