ASP.NET Core Blazor 환경

이 문서에서는 앱에서 환경을 구성하고 읽는 Blazor 방법을 설명합니다.

앱을 로컬에서 실행하면 환경이 기본적으로 Development로 설정됩니다. 앱이 게시되면 환경이 기본적으로 Production으로 설정됩니다.

다음 규칙을 사용하는 것이 좋습니다.

• 항상 로컬 개발에 "Development" 환경 이름을 사용합니다. ASP.NET Core 프레임워크는 앱의 로컬 개발 실행을 위한 앱 및 도구를 구성할 때 정확히 해당 이름을 예상하기 때문입니다.

• 테스트, 스테이징 및 프로덕션 환경의 경우 항상 앱을 게시하고 배포합니다. 게시된 앱에 대해 원하는 환경 명명 체계를 사용할 수 있지만 항상 환경 이름과 정확히 일치하는 환경 세그먼트의 대/소문자를 사용하여 앱 설정 파일 이름을 사용할 수 있습니다. 스테이징의 경우 환경 이름으로 "Staging"(대문자 "S")를 사용하고 일치시킬 앱 설정 파일의 이름을 지정합니다(appsettings.Staging.json). 프로덕션의 경우 환경 이름으로 "Production"(대문자 "P")를 사용하고 일치시킬 앱 설정 파일의 이름을 지정합니다(appsettings.Production.json).

환경 설정

환경을 설정하려면 다음 방법 중 하나를 사용합니다.

• Blazor 웹앱: 일반적인 ASP.NET Core 앱에 대해 ASP.NET Core 의 여러 환경 사용에 설명된 접근 방식을 사용합니다.
• Blazor 웹앱 또는 독립 실행형 Blazor WebAssembly: Blazor 구성 시작
• 독립 실행형 Blazor WebAssembly: blazor-environment 헤더
• Blazor웹앱 또는 독립 실행형Blazor WebAssembly: Azure 앱 Service

웹앱의 Blazor 클라이언트에서 환경은 이름이 지정된 blazor-environment헤더를 통해 환경을 브라우저와 통신하는 미들웨어를 통해 서버에서 결정됩니다. 헤더는 클라이언트 쪽 Program 파일(WebAssemblyHostBuilder.CreateDefault)에서 만들 때 WebAssemblyHost 환경을 설정합니다.

로컬에서 실행되는 독립 실행형 Blazor WebAssembly 앱의 경우 개발 서버에서 헤더를 blazor-environment 추가합니다.

개발 중인 앱의 로컬 실행의 경우 앱은 기본적으로 환경으로 Development 설정됩니다. 앱을 게시하면 환경이 기본적으로 .로 설정됩니다 Production.

시작 구성을 통해 Blazor 클라이언트 쪽 환경 설정

다음 예제는 호스트 이름에 localhost가 포함된 경우 Staging 환경에서 Blazor를 시작합니다. 그렇지 않으면 환경이 기본값으로 설정됩니다.

Blazor 웹앱:

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

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

참고 항목

구성에서 webAssemblyenvironment>Blazor.start 속성을 설정하는 Web Apps의 경우 Blazor 서버 쪽 환경을 속성에 environment 설정된 환경과 일치시키는 것이 좋습니다. 그렇지 않으면 서버의 미리 렌더링은 클라이언트에서 렌더링하는 것과 다른 환경에서 작동하므로 임의 효과가 발생합니다. 웹앱 환경 설정에 대한 Blazor 일반적인 지침은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

독립 실행형 Blazor WebAssembly:

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

앞의 예제 {BLAZOR SCRIPT} 에서 자리 표시자는 스크립트 경로 및 파일 이름입니다 Blazor . 스크립트의 위치는 ASP.NET Core Blazor 프로젝트 구조를 참조하세요.

environment 속성을 사용하여 blazor-environment 헤더로 설정된 환경을 재정의합니다.

이전 방법은 헤더의 값을 변경하지 blazor-environment 않고 클라이언트 환경을 설정하거나, 전역 Interactive WebAssembly 렌더링을 채택한 웹앱에 대한 Blazor 시작 환경의 서버 프로젝트의 콘솔 로깅을 변경하지 않습니다.

독립 실행형 Blazor WebAssembly 프로젝트 또는 .Client 웹앱 프로젝트의 Blazor 콘솔에 환경을 기록하려면 프로젝트를await builder.Build().RunAsync(); 빌드하고 실행하는 줄()을 WebAssemblyHostBuilder.CreateDefault 사용하여 만든 후 WebAssemblyHost 파일에 다음 C# 코드를 Program 배치합니다.

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

Blazor 시작에 대한 자세한 내용은 ASP.NET Core Blazor 시작을 참조하세요.

헤더를 통해 클라이언트 쪽 환경 설정

Blazor WebAssembly 앱은 헤더를 사용하여 환경을 blazor-environment 설정할 수 있습니다.

다음 IIS 예제에서는 게시된 web.config 파일에 사용자 지정 헤더(blazor-environment)를 추가합니다. web.config 파일은 bin/Release/{TARGET FRAMEWORK}/publish 폴더에 있습니다. 여기서 자리 표시자 {TARGET FRAMEWORK}는 대상 프레임워크입니다.

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

    ...

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

참고 항목

앱이 publish 폴더에 게시될 때 덮어쓰지 않는 IIS용 사용자 지정 web.config 파일을 사용하려면 ASP.NET Core Blazor WebAssembly 호스트 및 배포를 참조하세요.

프레임워크는 Blazor 모든 소문자(blazor-environment)로 헤더 이름을 발급하지만 원하는 모든 대/소문자를 사용할 수 있습니다. 예를 들어 각 단어(Blazor-Environment)를 대문자로 사용하는 헤더 이름이 지원됩니다.

Azure App Service에 대한 환경 설정

독립 실행형 Blazor WebAssembly 앱의 경우 시작 구성 또는 blazor-environment 헤더를 통해 환경을 수동으로 설정할 수 있습니다.

서버 쪽 앱의 경우 Azure에서 앱 설정을 통해 ASPNETCORE_ENVIRONMENT 환경을 설정합니다.

1. 앱 설정 파일 이름에서 환경 세그먼트의 대/소문자 구분이 환경 이름 대/소문자를 정확하게 일치시키는지 확인합니다. 예를 들어 환경에 대한 Staging 일치하는 앱 설정 파일 이름은 .입니다 appsettings.Staging.json. 파일 이름 appsettings.staging.json (소문자 "s")이면 파일이 없으므로 파일의 설정이 환경에서 사용되지 Staging 않습니다.

2. Visual Studio 배포의 경우 앱이 올바른 배포 슬롯에 배포되었는지 확인합니다. BlazorAzureAppSample라는 앱의 경우 앱은 Staging 배포 슬롯에 배포됩니다.

3. 환경의 배포 슬롯에 대한 Azure Portal에서 ASPNETCORE_ENVIRONMENT 앱 설정을 사용하여 환경을 설정합니다. BlazorAzureAppSample이라는 앱의 경우 스테이징 App Service 슬롯의 이름은 BlazorAzureAppSample/Staging입니다. Staging 슬롯의 구성에서 Staging 값을 사용하여 ASPNETCORE_ENVIRONMENT에 대한 앱 설정을 만듭니다. 설정에 대해 배포 슬롯 설정을 사용하도록 설정합니다.

브라우저에서 요청하는 경우 BlazorAzureAppSample/Staging 앱은 https://blazorazureappsample-staging.azurewebsites.net의 Staging 환경에서 로드됩니다.

앱이 브라우저에 로드되면 blazor.boot.json에 대한 응답 헤더 컬렉션은 blazor-environment 헤더 값이 Staging임을 나타냅니다.

appsettings.{ENVIRONMENT}.json 파일의 앱 설정은 앱에서 로드되며, 여기서 {ENVIRONMENT} 자리 표시자는 앱의 환경입니다. 위의 예제에서 appsettings.Staging.json 파일의 설정이 로드됩니다.

앱에서 Blazor WebAssembly 환경 읽기

IWebAssemblyHostEnvironment를 삽입하고 Environment 속성을 읽어 구성 요소에서 앱의 환경을 가져옵니다.

ReadEnvironment.razor:

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

<h1>Environment example</h1>

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

웹앱에서 환경 클라이언트 쪽 Blazor 읽기

구성 요소 또는 앱에 대해 미리 렌더링을 사용하지 않도록 설정하지 않은 경우 프로젝트의 구성 요소가 서버에서 .Client 미리 렌더링됩니다. 서버에 등록된 IWebAssemblyHostEnvironment 서비스가 없으므로 서버를 미리 렌더링하는 동안 서비스를 삽입하고 서비스 구현의 호스트 환경 확장 메서드 및 속성을 사용할 수 없습니다. Interactive WebAssembly 또는 Interactive Auto 구성 요소에 서비스를 삽입하면 다음과 같은 런타임 오류가 발생합니다.

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

이 문제를 해결하려면 서버에서 사용자 지정 서비스 구현 IWebAssemblyHostEnvironment 을 만듭니다. 서버 프로젝트에 다음 클래스를 추가합니다.

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;
}

서버 프로젝트의 Program 파일에서 서비스를 등록합니다.

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

이 시점에서 IWebAssemblyHostEnvironment 서비스는 대화형 WebAssembly 또는 대화형 자동 구성 요소에 삽입되고 앱 섹션의 환경 읽기 섹션 Blazor WebAssembly 에 표시된 대로 사용할 수 있습니다.

앞의 예제에서는 클라이언트 환경과 다른 서버 환경을 가질 수 있음을 보여 줄 수 있습니다. 이 환경은 권장되지 않으며 임의의 결과를 초래할 수 있습니다. 웹앱에서 Blazor 환경을 설정할 때 서버 및 프로젝트 환경과 .Client 일치하는 것이 가장 좋습니다. 테스트 앱에서 다음 시나리오를 고려합니다.

• 를 통해 Blazor.start환경을 사용하여 클라이언트 쪽(webassembly) 환경 속성을 Staging 구현합니다. 예제는 시작 구성 섹션을 통해 클라이언트 쪽 환경 설정을 참조하세요.
• 서버 쪽 Properties/launchSettings.json 파일을 변경하지 마세요. 환경 변수가 environmentVariables .로 설정된 상태로 섹션을 ASPNETCORE_ENVIRONMENT 그대로 둡 Development니다.

UI에서 속성 변경 값을 IWebAssemblyHostEnvironment.Environment 볼 수 있습니다.

서버에서 사전 렌더링이 발생하면 구성 요소가 환경에서 렌더링됩니다 Development .

Environment: Development

구성 요소가 1~2초 후에 Blazor 다시 렌더링되면 번들이 다운로드되고 Blazor WebAssembly 런타임이 활성화되면 클라이언트가 클라이언트 환경에서 Staging 작동하고 있음을 반영하도록 값이 변경됩니다.

Environment: Staging

앞의 예제에서는 개발, 테스트 및 프로덕션 배포를 위해 클라이언트 환경과 일치하도록 서버 환경을 설정하는 것이 좋습니다.

자세한 내용은 설명서의 뒷 Blazor 부분에 나오는 렌더링 모드 문서의 사전 렌더링 섹션에서 클라이언트 쪽 서비스가 확인되지 않는 것을 참조하세요.

시작하는 동안 클라이언트 쪽 환경 읽기

시작하는 동안 WebAssemblyHostBuilder는 HostEnvironment 속성을 통해 IWebAssemblyHostEnvironment를 노출하므로 호스트 빌더 코드에 환경 관련 논리를 사용할 수 있습니다.

Program 파일에서:

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

WebAssemblyHostEnvironmentExtensions를 통해 제공된 다음과 같은 편리한 확장 메서드로 Development, Production, Staging의 현재 환경 및 사용자 지정 환경 이름을 확인할 수 있습니다.

• IsDevelopment
• IsProduction
• IsStaging
• IsEnvironment

Program 파일에서:

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

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

NavigationManager 서비스를 사용할 수 없는 경우 시작하는 동안 IWebAssemblyHostEnvironment.BaseAddress 속성을 사용할 수 있습니다.

추가 리소스

• ASP.NET Core Blazor 시작
• ASP.NET Core에서 여러 환경 사용
• Blazor샘플 GitHub 리포지토리()(dotnet/blazor-samples다운로드 방법)