Lingkungan ASP.NET Core Blazor

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

Saat menjalankan aplikasi secara lokal, lingkungan secara default diatur 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" (huruf besar "P") sebagai nama lingkungan, dan beri nama file pengaturan aplikasi agar sesuai (appsettings.Production.json).

Mengatur lingkungan

Lingkungan diatur menggunakan salah satu pendekatan berikut:

• Blazor Web App atau Blazor Server: Gunakan salah satu pendekatan yang dijelaskan di lingkungan runtime ASP.NET Core untuk aplikasi umum ASP.NET Core.
• Aplikasi apa pun Blazor : Blazor mulai konfigurasi
• Mandiri Blazor WebAssembly: <WasmApplicationEnvironmentName> atribut

Pada klien untuk Blazor Web App, lingkungan ditentukan dari server melalui komentar HTML yang tidak berinteraksi dengan pengembang:

<!--Blazor-WebAssembly:{"environmentName":"Development", ...}-->

Untuk aplikasi mandiri Blazor WebAssembly , atur lingkungan dengan <WasmApplicationEnvironmentName> properti MSBuild di file proyek aplikasi (.csproj). Contoh berikut menyetel lingkungan Staging:

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

Lingkungan default adalah Development untuk build dan Production untuk dipublikasikan.

Ada beberapa pendekatan untuk mengatur lingkungan di aplikasi mandiri Blazor WebAssembly selama operasi build/publish dan satu pendekatan untuk aplikasi yang dimulai atau berjalan pada klien:

• Atur nilai properti saat dotnet build atau dotnet publish dijalankan. Contoh berikut mengatur lingkungan ke Staging saat aplikasi diterbitkan:

  dotnet publish -p:WasmApplicationEnvironmentName=Staging
  

• Atur properti selama build atau publikasikan berdasarkan konfigurasi aplikasi di Visual Studio. Grup properti berikut dapat digunakan dalam file proyek aplikasi atau file konfigurasi penerbitan apa pun (.pubxml). Tambahkan grup properti tambahan untuk konfigurasi build lain yang digunakan.

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Lingkungan dapat diatur berdasarkan penggunaan profil penerbitan. Dalam contoh berikut, kondisi pertama mengatur lingkungan ke Development ketika tidak ada profil penerbitan yang digunakan (berlaku untuk operasi build dan terbitkan tanpa profil), sementara kondisi kedua mencakup pengaturan lingkungan ke Production ketika profil publikasi digunakan:

  <PropertyGroup Condition="'$(PublishProfile)' == ''">
    <WasmApplicationEnvironmentName>Development</WasmApplicationEnvironmentName>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(PublishProfile)' != ''">
    <WasmApplicationEnvironmentName>Production</WasmApplicationEnvironmentName>
  </PropertyGroup>
  

• Buat titik akhir API web sisi server kustom. Aplikasi mandiri Blazor WebAssembly meminta lingkungannya dari API web baik di startup aplikasi atau sesuai permintaan saat sedang berjalan. Nilai harus diteruskan ke WebAssemblyStartOptions atau dengan withApplicationEnvironment.

  Nota

  Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag untuk rilis tertentu, gunakan menu dropdown Ganti cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Untuk aplikasi yang berjalan secara lokal selama tahap pengembangan, aplikasi akan menggunakan secara default lingkungan Development. Menerbitkan aplikasi mengatur lingkungan menjadi Production.

Mengatur lingkungan klien melalui konfigurasi startup Blazor

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} placeholder adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat Blazor proyek ASP.NET Core.

Nota

Untuk Blazor Web App yang menetapkan properti webAssembly>environment dalam konfigurasi Blazor.start, bijaksana untuk mencocokkan lingkungan sisi server dengan lingkungan yang diatur pada properti environment. Sebaliknya, prarendering di server beroperasi di bawah lingkungan yang berbeda dengan penyajian di klien, yang menghasilkan efek yang tidak menentu. Untuk panduan umum tentang mengatur lingkungan untuk Blazor Web App, lihat lingkungan runtime 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} placeholder adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat Blazor proyek ASP.NET Core.

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

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

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

Membaca lingkungan pada 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 IWebAssemblyHostEnvironment yang terdaftar, tidak memungkinkan untuk menyuntikkan layanan dan menggunakan metode serta properti ekstensi lingkungan host dari 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. Untuk informasi selengkapnya dan contoh implementasi, lihat implementasi layanan kustom di bagian server dari artikel Prarendering , 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 berikut yang disediakan melalui WebAssemblyHostEnvironmentExtensions memungkinkan untuk 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
• lingkungan runtime ASP.NET Core
• repositori GitHub contoh (Blazordotnet/blazor-samples) (cara mengunduh)