ASP.NET Core Razor 구성 요소 미리 렌더링

참고

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 10 버전을 참조하세요.

이 문서에서는 Razor s 및 Blazor Web App 앱의 서버 렌더링 구성 요소에 대한 구성 요소 미리 렌더링 시나리오를 Blazor Server설명합니다.

미리 렌더링 은 가능한 한 빨리 브라우저에 HTML을 제공하기 위해 서버에서 페이지 콘텐츠를 정적으로 렌더링하는 프로세스입니다. 미리 렌더링된 콘텐츠가 사용자에게 빠르게 표시되면 활성 이벤트 처리기가 있는 대화형 콘텐츠가 렌더링되어 이전에 렌더링된 콘텐츠를 대체합니다. 사전 렌더링은 검색 엔진이 페이지 순위를 계산하는 데 사용하는 초기 HTTP 응답에 대한 콘텐츠를 렌더링하여 SEO(검색 엔진 최적화) 를 향상시킬 수도 있습니다.

미리 렌더링은 기본적으로 대화형 구성 요소에 대해 사용하도록 설정됩니다.

대화형 라우팅을 사용하는 내부 탐색은 페이지가 이미 대화형이므로 미리 렌더링을 사용하지 않습니다. 자세한 내용은 정적 라우팅과 대화형 라우팅 및 대화형 라우팅 및 미리 렌더링을 참조하세요.

OnAfterRender{Async} 구성 요소 수명 주기 이벤트는 구성 요소가 대화형으로 렌더링된 후에만 미리 렌더링할 때 호출되지 않습니다.

미리 렌더링 사용 안 함

미리 렌더링하면 앱의 Razor 구성 요소가 두 번 렌더링되어야 하기 때문에 앱이 복잡해질 수 있습니다. 즉, 사전 렌더링을 위해 한 번, 대화형 작업을 설정하기 위해 한 번 렌더링해야 합니다. 구성 요소가 WebAssembly에서 실행되도록 설정된 경우 서버와 클라이언트 모두에서 실행할 수 있도록 구성 요소를 디자인해야 합니다.

구성 요소 인스턴스에 대해 사전 렌더링을 비활성화하려면 플래그에 prerender 값을 설정하여 렌더 모드로 전달하십시오.

<... @rendermode="new InteractiveServerRenderMode(prerender: false)" />
<... @rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" />
<... @rendermode="new InteractiveAutoRenderMode(prerender: false)" />

구성 요소 정의에서 미리 렌더링을 사용하지 않도록 설정하려면 다음을 수행합니다.

@rendermode @(new InteractiveServerRenderMode(prerender: false))
@rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))
@rendermode @(new InteractiveAutoRenderMode(prerender: false))

전체 앱에 대해 미리 렌더링을 사용하지 않도록 설정하려면 루트 구성 요소가 아닌 앱의 구성 요소 계층 구조에서 가장 높은 수준의 대화형 구성 요소에 렌더링 모드를 표시합니다.

프로젝트 템플릿 Blazor Web App을 기반으로 하는 앱의 경우, Routes 구성 요소에서 App 구성 요소가 사용되는 위치에 전체 앱에 할당된 렌더 모드가 Components/App.razor로 지정됩니다. 다음 예제에서는 미리 렌더링을 사용하지 않도록 설정된 앱의 렌더링 모드를 Interactive Server로 설정합니다.

<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />

HeadOutlet 구성 요소의 에 대해 미리 렌더링을 비활성화합니다.

<HeadOutlet @rendermode="new InteractiveServerRenderMode(prerender: false)" />

루트 구성 요소 정의 파일(App)의 맨 위에 있는 @rendermode 지시문을 사용하여 루트 구성 요소, 예를 들어 .razor 구성 요소를 대화형으로 만드는 것은 지원되지 않습니다. 따라서 미리 렌더링은 구성 요소에서 App 직접 사용하지 않도록 설정할 수 없습니다.

이전 기술을 사용하여 미리 렌더링을 사용하지 않도록 설정하면 최상위 렌더링 모드에만 적용됩니다. 부모 구성 요소가 렌더링 모드를 지정하는 경우 자식의 미리 렌더링 설정은 무시됩니다.

미리 렌더링된 상태 유지

미리 렌더링된 상태를 유지하지 않으면 미리 렌더링하는 동안 사용된 상태를 잃게 되며 앱이 완전히 로드되면 다시 만들어야 합니다. 비동기적으로 상태가 만들어지면 구성 요소가 다시 렌더링될 때 미리 렌더링된 UI가 대체되므로 UI가 깜박일 수 있습니다. 미리 렌더링하는 동안 상태를 유지하는 방법에 대한 지침은 ASP.NET Core Blazor 미리 렌더링된 상태 지속성을 참조하세요.

미리 렌더링하는 동안 클라이언트 측 서비스가 해결되지 않습니다.

구성 요소 또는 앱에 대해 미리 렌더링을 사용하지 않도록 설정하지 않은 경우 프로젝트의 구성 요소가 서버에서 .Client 미리 렌더링됩니다. 서버에 등록된 클라이언트 쪽 Blazor 서비스에 대한 액세스 권한이 없으므로 미리 렌더링하는 동안 서비스를 찾을 수 없다는 오류를 받지 않고는 이러한 서비스를 구성 요소에 삽입할 수 없습니다.

예를 들어 전역 Interactive WebAssembly 또는 대화형 자동 렌더링을 사용하는 Home프로젝트에서 다음 .Client 구성 요소를 Blazor Web App 고려합니다. 구성 요소는 환경의 이름을 얻기 위해 삽입 IWebAssemblyHostEnvironment 을 시도합니다.

@page "/"
@inject IWebAssemblyHostEnvironment Environment

<PageTitle>Home</PageTitle>

<h1>Home</h1>

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

컴파일 시간 오류는 발생하지 않지만 사전 렌더링 중에 런타임 오류가 발생합니다.

'BlazorSample.Client.PagesHome' 형식의 속성 'Environment'에 대한 값을 제공할 수 없습니다. 'Microsoft.AspNetCore.Components.WebAssembly.Hosting.IWebAssemblyHostEnvironment' 형식의 등록된 서비스가 없습니다.

이 오류는 구성 요소가 미리 렌더링하는 동안 서버에서 컴파일되고 실행되어야 하지만 IWebAssemblyHostEnvironment 서버에 등록된 서비스가 아니기 때문에 발생합니다.

이 시나리오를 해결하려면 다음 방법 중 어느 것을 고려하세요.

클라이언트 외에도 서버에 서비스 등록
미리 렌더링하는 동안 앱에서 사용할 수 있는 서비스 삽입
서비스를 선택 사항으로 만들기
서비스 추상화 만들기
구성 요소에 대한 미리 렌더링 사용 안 함

클라이언트 외에도 서버에 서비스 등록

서비스가 서버 실행을 지원하는 경우 사전 렌더링 중에 사용할 수 있도록 클라이언트 외에 서버에 서비스를 등록합니다. 이 시나리오의 예제는 HttpClient 문서의 외부 웹 API 섹션에 있는Blazor Web App 서비스에 대한 지침을 참조하세요.

미리 렌더링하는 동안 앱에서 사용할 수 있는 서비스 삽입

경우에 따라 앱은 미리 렌더링하는 동안 서버에서 서비스를 사용하고 클라이언트에서 다른 서비스를 사용할 수 있습니다.

예를 들어 다음 코드는 IHostEnvironment 환경을 가져옵니다.Microsoft.Extensions.Hosting.Abstractions

private string? environmentName;

public Home(IHostEnvironment? serverEnvironment = null, 
    IWebAssemblyHostEnvironment? wasmEnvironment = null)
{
    environmentName = serverEnvironment?.EnvironmentName;
    environmentName ??= wasmEnvironment?.Environment;
}

그러나 이 방법은 필요하지 않은 클라이언트 프로젝트에 추가 종속성을 추가합니다.

서비스를 선택 사항으로 만들기

다음 방법 중 하나를 사용하여 미리 렌더링하는 동안 필요하지 않은 경우 서비스를 선택적으로 만듭니다.

다음 예제에서는 IWebAssemblyHostEnvironment의 생성자 주입을 사용합니다.

private string? environmentName;

public Home(IWebAssemblyHostEnvironment? env = null)
{
    environmentName = env?.Environment;
}

서비스를 사용할 수 있는 경우에는 선택적으로 가져오기 위해 IServiceProvider을(를) 삽입합니다.

@page "/"
@using Microsoft.AspNetCore.Components.WebAssembly.Hosting
@inject IServiceProvider Services

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<p>
    <b>Environment:</b> @environmentName
</p>

@code {
    private string? environmentName;

    protected override void OnInitialized()
    {
        if (Services.GetService<IWebAssemblyHostEnvironment>() is { } env)
        {
            environmentName = env.Environment;
        }
    }
}

서비스 추상화 만들기

서버에서 다른 서비스 구현이 필요한 경우 서비스 추상화 및 서버 및 클라이언트 프로젝트에서 서비스에 대한 구현을 만듭니다. 각 프로젝트에 서비스를 등록합니다. 필요한 경우 구성 요소에 사용자 지정 서비스 추상화 삽입 그런 다음 구성 요소는 사용자 지정 서비스 추상화에만 의존합니다.

이 경우 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 또는 자동 구성 요소에 삽입할 수 있습니다.

구성 요소에 대한 미리 렌더링 사용 안 함

구성 요소 또는 전체 앱에 대해 미리 렌더링을 사용하지 않도록 설정합니다. 자세한 내용은 미리 렌더링 사용 안 함 섹션을 참조하세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-19