ASP.NET Core Blazor 렌더링 모드

이 문서에서는 컴파일 시간 또는 런타임에 Blazor Web App구성 요소 렌더링의 제어 Razor 를 설명합니다.

이 지침은 독립 실행형 Blazor WebAssembly 앱에는 적용되지 않습니다. Blazor WebAssembly앱은 클라이언트 쪽 WebAssembly 기반 런타임을 통해서만 클라이언트에서 렌더링되며 렌더링 모드의 개념이 없습니다. 렌더링 모드가 앱의 구성 요소에 Blazor WebAssembly 적용되는 경우 렌더링 모드 지정은 구성 요소 렌더링에 영향을 주지 않습니다.

렌더링 모드

모든 구성 요소는 렌더링 모드를 Blazor Web App 채택하여 사용하는 호스팅 모델, 렌더링되는 위치 및 대화형인지 여부를 결정합니다.

다음 표에서는 구성 요소를 렌더링하는 데 사용할 수 있는 렌더링 모드를 Razor 보여 Blazor Web App줍니다. 구성 요소에 렌더링 모드를 적용하려면 구성 요소 인스턴스 또는 구성 요소 정의에서 지시문을 사용합니다 @rendermode . 이 문서의 뒷부분에는 각 렌더링 모드 시나리오에 대한 예제가 나와 있습니다.

속성	설명	렌더링 위치	대화형
정적 서버	정적 서버 쪽 렌더링(정적 SSR)	서버	❌문제
대화형 서버	를 사용하는 Blazor Server대화형 서버 쪽 렌더링(대화형 SSR)	서버	✔️예
Interactive WebAssembly	† 사용하는 Blazor WebAssemblyCSR(클라이언트 쪽 렌더링)	클라이언트	✔️예
대화형 자동	번들이 다운로드된 후 후속 방문 시 처음에는 CSR을 Blazor 사용하는 Blazor Server 대화형 SSR입니다.	서버, 클라이언트	✔️예

†CSR(Client side rendering)은 대화형으로 간주됩니다. "대화형 클라이언트 쪽 렌더링" 및 "대화형 CSR"은 업계 또는 설명서에서 Blazor 사용되지 않습니다.

미리 렌더링은 기본적으로 대화형 구성 요소에 대해 사용하도록 설정됩니다. 미리 렌더링 제어에 대한 지침은 이 문서의 뒷부분에 나와 있습니다. 클라이언트 및 서버 렌더링 개념에 대한 일반적인 업계 용어는 ASP.NET Core Blazor 기본 사항을 참조하세요.

다음 예제에서는 몇 가지 기본 Razor 구성 요소 기능을 사용하여 구성 요소의 렌더링 모드를 설정하는 방법을 보여 줍니다.

렌더링 모드 동작을 로컬로 테스트하려면 프로젝트 템플릿에서 Blazor Web App 만든 앱에 다음 구성 요소를 배치할 수 있습니다. 앱을 만들 때 드롭다운 메뉴(Visual Studio)에서 옵션을 선택하거나 CLI 옵션(.NET CLI)을 적용하여 서버 쪽 및 클라이언트 쪽 대화형 작업을 모두 사용하도록 설정합니다. 만드는 Blazor Web App방법에 대한 지침은 ASP.NET Core용 도구를 참조 하세요 Blazor.

대화형 렌더링 모드에 대한 지원 사용

대화형 렌더링 모드를 지원하도록 A Blazor Web App 를 구성해야 합니다. 다음 확장은 앱을 만드는 동안 프로젝트 템플릿에서 만든 앱에 Blazor Web App 자동으로 적용됩니다. 구성 요소 서비스 및 엔드포인트가 앱 Program 의 파일에 구성된 후에도 개별 구성 요소는 렌더링 모드 섹션에 따라 렌더링 모드를 선언해야 합니다.

구성 요소에 대한 Razor 서비스는 호출 AddRazorComponents을 통해 추가됩니다.

구성 요소 작성기 확장:

• AddInteractiveServerComponents 는 대화형 서버 구성 요소 렌더링을 지원하는 서비스를 추가합니다.
• AddInteractiveWebAssemblyComponents 는 대화형 WebAssembly 구성 요소 렌더링을 지원하는 서비스를 추가합니다.

MapRazorComponents는 사용 가능한 구성 요소를 검색하고 앱의 루트 구성 요소(로드된 첫 번째 구성 요소)를 지정하며, 기본적으로 구성 요소(App.razor)입니다App.

엔드포인트 규칙 작성기 확장:

• AddInteractiveServerRenderMode 는 앱에 대한 대화형 SSR(대화형 서버 쪽 렌더링)을 구성합니다.
• AddInteractiveWebAssemblyRenderMode 는 앱에 대한 Interactive WebAssembly 렌더링 모드를 구성합니다.

참고 항목

다음 예제에서 API 배치에 대한 방향을 보려면 프로젝트 템플릿에서 Blazor Web App 생성된 앱의 파일을 검사 Program 합니다. 만드는 Blazor Web App방법에 대한 지침은 ASP.NET Core용 도구를 참조 하세요 Blazor.

예제 1: 다음 Program 파일 API는 대화형 SSR을 사용하도록 설정하기 위한 서비스 및 구성을 추가합니다.

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

예제 2: 다음 Program 파일 API는 Interactive WebAssembly 렌더링 모드를 사용하도록 설정하기 위한 서비스와 구성을 추가합니다.

builder.Services.AddRazorComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode();

예제 3: 다음 Program 파일 API는 대화형 서버, 대화형 WebAssembly 및 대화형 자동 렌더링 모드를 사용하도록 설정하기 위한 서비스 및 구성을 추가합니다.

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode();

Blazor 는 Blazor WebAssembly 호스팅 모델을 사용하여 Interactive WebAssembly 렌더링 모드를 사용하는 구성 요소를 다운로드하고 실행합니다. 이러한 구성 요소에 대한 호스팅을 설정 Blazor WebAssembly 하려면 별도의 클라이언트 프로젝트가 필요합니다. 클라이언트 프로젝트는 호스트에 대한 Blazor WebAssembly 시작 코드를 포함하고 브라우저에서 실행하기 위한 .NET 런타임을 설정합니다. Blazor Web App WebAssembly 대화형 작업을 사용하도록 설정하는 옵션을 선택하면 템플릿에서 이 클라이언트 프로젝트를 추가합니다. Interactive WebAssembly 렌더링 모드를 사용하는 모든 구성 요소는 클라이언트 프로젝트에서 빌드되어야 하므로 다운로드한 앱 번들에 포함됩니다.

구성 요소 인스턴스에 렌더링 모드 적용

구성 요소 인스턴스에 렌더링 모드를 적용하려면 구성 요소가 사용되는 지시문 특성을 사용합니다@rendermodeRazor.

다음 예제에서는 대화형 서버 쪽 렌더링(대화형 SSR)이 구성 요소 인스턴스에 Dialog 적용됩니다.

<Dialog @rendermode="InteractiveServer" />

참고 항목

Blazor템플릿에는 더 짧은 @rendermode 구문에 대한 앱 _Imports 파일(Components/_Imports.razor)에 대한 RenderMode 정적 using 지시문이 포함됩니다.

@using static Microsoft.AspNetCore.Components.Web.RenderMode

이전 지시문이 없으면 구성 요소는 구문에서 @rendermode 정적 RenderMode 클래스를 지정해야 합니다.

<Dialog @rendermode="RenderMode.InteractiveServer" />

사용자 지정 구성을 사용하여 직접 인스턴스화된 사용자 지정 렌더링 모드 인스턴스를 참조할 수도 있습니다. 자세한 내용은 이 문서의 뒷부분에 있는 사용자 지정 약식 렌더링 모드 섹션을 참조하세요.

구성 요소 정의에 렌더링 모드 적용

구성 요소의 렌더링 모드를 정의의 일부로 지정하려면 지시문 및 해당 렌더링 모드 특성을 사용합니다Razor@rendermode.

@page "..."
@rendermode InteractiveServer

렌더링 모드를 구성 요소 정의에 적용하는 것은 일반적으로 특정 페이지에 렌더링 모드를 적용할 때 사용됩니다. 라우팅 가능한 페이지는 페이지를 렌더링한 구성 요소와 Router 동일한 렌더링 모드를 사용합니다.

기술적으로 지시 @rendermode 문 및Razor 지시문 특성입니다Razor. 의미 체계는 비슷하지만 차이점이 있습니다. 지시문은 @rendermode 구성 요소 정의에 있으므로 참조된 렌더링 모드 인스턴스는 정적이어야 합니다. 지시문 특성은 @rendermode 렌더링 모드 인스턴스를 사용할 수 있습니다.

참고 항목

구성 요소 작성자는 구성 요소의 구현을 특정 렌더링 모드에 결합하지 않아야 합니다. 대신 구성 요소 작성자는 일반적으로 렌더링 모드 또는 호스팅 모델을 지원하도록 구성 요소를 디자인해야 합니다. 구성 요소의 구현은 실행 중인 위치(서버 또는 클라이언트)에 대한 가정을 피해야 하며 정적으로 렌더링될 때 정상적으로 저하되어야 합니다. 구성 요소가 직접 인스턴스화되지 않거나(예: 라우팅 가능한 페이지 구성 요소 포함) 모든 구성 요소 인스턴스에 대한 렌더링 모드를 지정하려면 구성 요소 정의에서 렌더링 모드를 지정해야 할 수 있습니다.

전체 앱에 렌더링 모드 적용

전체 앱에 대한 렌더링 모드를 설정하려면 루트 구성 요소가 아닌 앱의 구성 요소 계층 구조에서 가장 높은 수준의 대화형 구성 요소에서 렌더링 모드를 나타냅니다.

참고 항목

구성 요소와 같은 루트 구성 요소를 대화형으로 App 만드는 것은 지원되지 않습니다. 따라서 전체 앱의 렌더링 모드는 구성 요소에서 App 직접 설정할 수 없습니다.

프로젝트 템플릿을 기반으로 하는 앱의 Blazor Web App 경우 전체 앱에 할당된 렌더링 모드는 일반적으로 구성 요소에서 App 구성 요소가 사용되는 위치Routes(Components/App.razor)로 지정됩니다.

<Routes @rendermode="InteractiveServer" />

Router 구성 요소는 해당 렌더링 모드를 라우팅하는 페이지로 전파합니다.

또한 일반적으로 프로젝트 템플릿에서 생성된 구성 요소에도 있는 구성 요소에서 동일한 대화형 렌더링 모드HeadOutlet를 Blazor Web App 설정해야 App 합니다.

<HeadOutlet @rendermode="InteractiveServer" />

대화형 클라이언트 쪽(WebAssembly 또는 자동) 렌더링 모드를 채택하고 구성 요소를 통해 Routes 전체 앱에 대한 렌더링 모드를 사용하도록 설정하는 앱의 경우:

• 서버 앱 Components/Layout 폴더의 레이아웃 및 탐색 파일을 프로젝트 Layout 폴더로 .Client 이동하거나 배치합니다. Layout 존재하지 않는 경우 프로젝트에 폴더 .Client 를 만듭니다.
• 서버 앱 Components/Pages 폴더의 구성 요소를 프로젝트의 Pages 폴더로 .Client 배치하거나 이동합니다. Pages 존재하지 않는 경우 프로젝트에 폴더 .Client 를 만듭니다.
• 서버 앱 Components 폴더의 구성 요소를 프로젝트의 루트 폴더로 .Client 배치하거나 이동합니다Routes.

다음을 만들 Blazor Web App때 전역 대화형 작업을 사용하도록 설정하려면:

• Visual Studio: 대화형 작업 위치 드롭다운 목록을 전역으로 설정합니다.
• .NET CLI: 옵션을 -ai|--all-interactive 사용합니다.

자세한 내용은 ASP.NET Core Blazor 도구를 참조하세요.

프로그래밍 방식으로 렌더링 모드 적용

속성 및 필드는 렌더링 모드를 할당할 수 있습니다.

구성 요소 인스턴스별로 렌더링 모드를 설정하는 이 섹션에서 설명하는 두 번째 방법은 앱 사양에서 하나 이상의 구성 요소가 전역 대화형 앱에서 정적 SSR을 채택하도록 요구하는 경우에 특히 유용합니다. 이 시나리오는 이 문서의 뒷부 분에 있는 전역 대화형 앱 섹션의 정적 SSR 페이지에서 다룹니다.

구성 요소 정의별 렌더링 모드 설정

구성 요소 정의는 프라이빗 필드를 통해 렌더링 모드를 정의할 수 있습니다.

@rendermode pageRenderMode

...

@code {
    private static IComponentRenderMode pageRenderMode = InteractiveServer;
}

구성 요소 인스턴스별 렌더링 모드 설정

다음 예제에서는 모든 요청에 대화형 서버 쪽 렌더링(대화형 SSR)을 적용합니다.

<Routes @rendermode="PageRenderMode" />

...

@code {
    private IComponentRenderMode? PageRenderMode => InteractiveServer;
}

렌더링 모드 전파에 대한 추가 정보는 이 문서의 뒷부분에 있는 렌더링 모드 전파 섹션에서 제공됩니다. 전역 대화형 앱 섹션의 정적 SSR 페이지는 이전 방법을 사용하여 전역 대화형 앱에서 정적 SSR을 채택하는 방법을 보여 줍니다.

런타임에 렌더링 위치, 대화형 작업 및 할당된 렌더링 모드 검색

ComponentBase.RendererInfo 및 ComponentBase.AssignedRenderMode 속성을 사용하면 앱이 구성 요소의 위치, 대화형 작업 및 할당된 렌더링 모드에 대한 세부 정보를 검색할 수 있습니다.

• RendererInfo.Name 는 구성 요소가 실행되는 위치를 반환합니다.
  • Static: 서버(SSR)에서 대화형 작업을 수행할 수 없습니다.
  • Server: 서버(SSR)에서 사전 렌더링 후 대화형 작업을 수행할 수 있습니다.
  • WebAssembly: 클라이언트(CSR)에서 사전 렌더링 후 대화형 작업을 수행할 수 있습니다.
  • WebView: 네이티브 디바이스에서 미리 렌더링한 후 대화형 작업을 수행할 수 있습니다.
• RendererInfo.IsInteractive 는 렌더링 시 구성 요소가 대화형 작업을 지원하는지 나타냅니다. 값은 true 대화형으로 렌더링하거나 미리 렌더링하거나 false 정적 SSR(RendererInfo.Name 의)에 Static대한 경우입니다.
• ComponentBase.AssignedRenderMode 는 구성 요소의 할당된 렌더링 모드를 노출합니다.
  • InteractiveServer 대화형 서버의 경우
  • InteractiveAuto 대화형 자동의 경우
  • InteractiveWebAssembly 대화형 WebAssembly의 경우

구성 요소는 이러한 속성을 사용하여 위치 또는 대화형 상태에 따라 콘텐츠를 렌더링합니다. 다음 예제에서는 일반적인 사용 사례를 보여 줍니다.

구성 요소가 대화형일 때까지 콘텐츠를 표시합니다.

@if (!RendererInfo.IsInteractive)
{
    <p>Connecting to the assistant...</p>
}
else
{
    ...
}

구성 요소가 대화형일 때까지 단추를 사용하지 않도록 설정합니다.

<button @onclick="Send" disabled="@(!RendererInfo.IsInteractive)">
    Send
</button>

미리 렌더링하는 동안 양식을 사용하지 않도록 설정하고 구성 요소가 대화형일 때 양식을 사용하도록 설정합니다.

<EditForm Model="Movie" ...>
    <fieldset disabled="@disabled">

        ...

        <button type="submit" >Save</button>
    </fieldset>
</EditForm>

@code {
    private bool disabled = true;

    [SupplyParameterFromForm]
    private Movie? Movie { get; set; }

    protected override async Task OnInitializedAsync()
    {
        Movie ??= await ...;

        if (RendererInfo.IsInteractive)
        {
            disabled = false;
        }
    }
}

구성 요소가 정적으로 렌더링되는 경우 일반 HTML 동작 수행을 지원하도록 태그를 렌더링합니다.

@if (AssignedRenderMode is null)
{
    // The render mode is Static Server
    <form action="/movies">
        <input type="text" name="titleFilter" />
        <input type="submit" value="Search" />
    </form>
}
else
{
    // The render mode is Interactive Server, WebAssembly, or Auto
    <input @bind="titleFilter" />
    <button @onclick="FilterMovies">Search</button>
}

앞의 예에서:

• 값 AssignedRenderMode 이면 null구성 요소는 정적 SSR을 채택합니다. Blazor이벤트 처리는 정적 SSR이 있는 브라우저에서 작동하지 않으므로 구성 요소는 쿼리 문자열이 사용자 <input> 값으로 titleFilter 설정된 양식(GET 요청)을 제출합니다. 구성 요소(/movie)는 Movie 쿼리 문자열을 읽고 필터링된 결과로 구성 요소를 렌더링하는 값을 titleFilter 처리할 수 있습니다.
• 그렇지 않으면 렌더링 모드는 InteractiveServer, InteractiveWebAssembly또는 InteractiveAuto. 구성 요소는 이벤트 처리기 대리자()와 요소(FilterMoviestitleFilter)에 <input> 바인딩된 값을 사용하여 백그라운드 SignalR 연결을 통해 대화형으로 영화를 필터링할 수 있습니다.

Blazor 에 대한 Blazor Web App설명서 예제

사용 시 Blazor Web App대부분의 설명서 예제 구성 요소에는 상호 작용이 필요하며 문서에서 다루는 개념을 보여 Blazor 줍니다. 아티클에서 제공하는 예제 구성 요소를 테스트할 때 앱이 전역 대화형 대화형 작업을 채택하거나 구성 요소가 대화형 렌더링 모드를 채택하는지 확인합니다.

미리 렌더링

미리 렌더링 은 렌더링된 컨트롤에 대한 이벤트 처리기를 사용하도록 설정하지 않고 서버에서 페이지 콘텐츠를 처음 렌더링하는 프로세스입니다. 서버는 초기 요청에 대한 응답으로 가능한 한 빨리 페이지의 HTML UI를 출력하므로 앱이 사용자에게 더 반응할 수 있습니다. 사전 렌더링은 검색 엔진이 페이지 순위를 계산하는 데 사용하는 초기 HTTP 응답에 대한 콘텐츠를 렌더링하여 SEO(검색 엔진 최적화)를 향상시킬 수도 있습니다.

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

대화형 라우팅에 대한 내부 탐색에는 서버에서 새 페이지 콘텐츠를 요청하는 작업이 포함되지 않습니다. 따라서 향상된 탐색을 포함하여 내부 페이지 요청에 대해 미리 렌더링이 발생하지 않습니다. 자세한 내용은 정적 라우팅과 대화형 라우팅, 대화형 라우팅 및 사전 렌더링, 향상된 탐색 및 양식 처리를 참조하세요.

다음 기술을 사용하여 미리 렌더링을 사용하지 않도록 설정하면 최상위 렌더링 모드에만 적용됩니다. 부모 구성 요소가 렌더링 모드를 지정하는 경우 자식의 미리 렌더링 설정은 무시됩니다. 이 동작은 2025년 11월에 .NET 10이 릴리스될 때 변경될 수 있는지 조사 중입니다.

구성 요소 인스턴스에 대한 미리 렌더링을 사용하지 않도록 설정하려면 값 false 이 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 경우 구성 요소(Components/App.razor)에서 구성 요소가 사용되는 위치에 Routes 전체 앱에 할당된 렌더링 모드가 App 지정됩니다. 다음 예제에서는 미리 렌더링을 사용하지 않도록 설정된 앱의 렌더링 모드를 Interactive Server로 설정합니다.

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

또한 구성 요소의 구성 요소에 대한 미리 렌더링을 App HeadOutlet 사용하지 않도록 설정합니다.

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

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

정적 서버 쪽 렌더링(정적 SSR)

구성 요소는 정적 서버 쪽 렌더링(정적 SSR)을 사용합니다. 구성 요소가 응답 스트림에 렌더링되고 대화형 작업이 사용되지 않습니다.

다음 예제에서는 구성 요소의 렌더링 모드에 대한 지정이 없으므로 구성 요소는 부모로부터 렌더링 모드를 상속합니다. 상위 구성 요소가 렌더링 모드를 지정하지 않으므로 다음 구성 요소는 서버에서 정적으로 렌더링됩니다 . 단추는 대화형이 아니며 선택할 때 메서드를 UpdateMessage 호출하지 않습니다. 값 message 은 변경되지 않으며 구성 요소는 UI 이벤트에 대한 응답으로 다시 렌더링되지 않습니다.

RenderMode1.razor:

@page "/render-mode-1"

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

위의 구성 요소를 로컬로 Blazor Web App사용하는 경우 구성 요소를 서버 프로젝트의 Components/Pages 폴더에 배치합니다. 서버 프로젝트는 이름이 .Client종료되지 않는 솔루션의 프로젝트입니다. 앱이 실행 중이면 브라우저의 주소 표시줄로 이동합니다 /render-mode-1 .

정적 SSR Razor 중에 구성 요소 페이지 요청은 라우팅 및 권한 부여를 위한 서버 쪽 ASP.NET Core 미들웨어 파이프라인 요청 처리에 의해 처리됩니다. 서버 쪽 요청 처리 중에 구성 요소가 렌더링되지 않으므로 라우팅 및 권한 부여에 대한 전용 Blazor 기능은 작동하지 Razor 않습니다. Blazor 정적 SSR 중에 사용할 수 없는 구성 요소의 라우터 기능에 Routes 는 다음 표시가 포함됩니다.

• 권한 없는 콘텐츠()(<NotAuthorized>...</NotAuthorized>): 일반적으로 권한 부여 미들웨어의 동작을 사용자 지정하여 서버에서 권한 없는 요청을 처리합니다. Blazor Web AppNotAuthorized

• 찾을 수 없는 콘텐츠()(<NotFound>...</NotFound>): 일반적으로 브라우저의 기본 제공 404 UI를 표시하거나 ASP.NET Core 미들웨어(예UseStatusCodePagesWithRedirects / : API 설명서)를 통해 사용자 지정 404 페이지(또는 기타 응답)를 반환하여 서버에서 잘못된 URL 요청을 처리합니다. Blazor Web AppNotFound

앱이 루트 수준 대화형 작업을 표시하는 경우 서버 쪽 ASP.NET Core 요청 처리는 초기 정적 SSR 이후에 관련되지 않습니다. 즉, 이전 Blazor 기능이 예상대로 작동합니다.

정적 SSR을 사용한 향상된 탐색 은 JavaScript를 로드할 때 특별히 주의해야 합니다. 자세한 내용은 정적 서버 쪽 렌더링(정적 SSR)이 있는 ASP.NET Core Blazor JavaScript를 참조하세요.

대화형 서버 쪽 렌더링(대화형 SSR)

대화형 서버 쪽 렌더링(대화형 SSR)은 구성 요소를 서버 Blazor Server에서 대화형으로 렌더링합니다. 사용자 상호 작용은 브라우저와의 실시간 연결을 통해 처리됩니다. 회로 연결은 서버 구성 요소가 렌더링될 때 설정됩니다.

다음 예제에서 렌더링 모드는 구성 요소 정의에 추가하여 @rendermode InteractiveServer 대화형 SSR을 설정합니다. 이 단추는 선택할 때 메서드를 UpdateMessage 호출합니다. 변경 내용 값 message 과 구성 요소가 다시 렌더링되어 UI의 메시지를 업데이트합니다.

RenderMode2.razor:

@page "/render-mode-2"
@rendermode InteractiveServer

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

이전 구성 요소를 사용하는 Blazor Web App경우 구성 요소를 서버 프로젝트의 Components/Pages 폴더에 배치합니다. 서버 프로젝트는 이름이 .Client종료되지 않는 솔루션의 프로젝트입니다. 앱이 실행 중이면 브라우저의 주소 표시줄로 이동합니다 /render-mode-2 .

CSR(클라이언트 쪽 렌더링)

CSR(클라이언트 쪽 렌더링)은 구성 요소를 클라이언트 Blazor WebAssembly에서 대화형으로 렌더링합니다. .NET 런타임 및 앱 번들은 WebAssembly 구성 요소가 처음 렌더링될 때 다운로드되고 캐시됩니다. CSR을 사용하는 구성 요소는 호스트를 설정하는 Blazor WebAssembly 별도의 클라이언트 프로젝트에서 빌드해야 합니다.

다음 예제에서는 렌더링 모드가 을 사용하여 CSR로 @rendermode InteractiveWebAssembly설정됩니다. 이 단추는 선택할 때 메서드를 UpdateMessage 호출합니다. 변경 내용 값 message 과 구성 요소가 다시 렌더링되어 UI의 메시지를 업데이트합니다.

RenderMode3.razor:

@page "/render-mode-3"
@rendermode InteractiveWebAssembly

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

위의 구성 요소를 로컬로 Blazor Web App사용하는 경우 클라이언트 프로젝트의 Pages 폴더에 구성 요소를 배치합니다. 클라이언트 프로젝트는 이름이 끝나는 솔루션의 프로젝트입니다 .Client. 앱이 실행 중이면 브라우저의 주소 표시줄로 이동합니다 /render-mode-3 .

자동(자동) 렌더링

자동(자동) 렌더링은 런타임에 구성 요소를 렌더링하는 방법을 결정합니다. 구성 요소는 처음에 호스팅 모델을 사용하여 Blazor Server 대화형 서버 쪽 렌더링(대화형 SSR)으로 렌더링됩니다. .NET 런타임 및 앱 번들은 백그라운드에서 클라이언트에 다운로드되고 나중에 방문할 때 사용할 수 있도록 캐시됩니다.

자동 렌더링 모드는 페이지에 이미 있는 구성 요소의 렌더링 모드를 동적으로 변경하지 않습니다. 자동 렌더링 모드는 구성 요소에 사용할 대화형 작업 유형에 대한 초기 결정을 내린 다음, 구성 요소는 페이지에 있는 한 해당 유형의 대화형 작업을 유지합니다. 이 초기 결정의 한 가지 요인은 WebAssembly/Server 대화형 작업을 사용하여 구성 요소가 페이지에 이미 있는지 여부를 고려하는 것입니다. 자동 모드는 기존 대화형 구성 요소의 렌더링 모드와 일치하는 렌더링 모드를 선택하는 것을 선호합니다. 자동 모드에서 기존 대화형 모드를 사용하는 것을 선호하는 이유는 기존 런타임과 상태를 공유하지 않는 새 대화형 런타임을 도입하지 않기 위해서입니다.

자동 렌더링 모드를 사용하는 구성 요소는 호스트를 설정하는 Blazor WebAssembly 별도의 클라이언트 프로젝트에서 빌드해야 합니다.

다음 예제에서 구성 요소는 프로세스 전체에서 대화형입니다. 이 단추는 선택할 때 메서드를 UpdateMessage 호출합니다. 변경 내용 값 message 과 구성 요소가 다시 렌더링되어 UI의 메시지를 업데이트합니다. 처음에는 구성 요소가 서버에서 대화형으로 렌더링되지만 이후 방문 시 .NET 런타임 및 앱 번들이 다운로드되고 캐시된 후 클라이언트에서 렌더링됩니다.

RenderMode4.razor:

@page "/render-mode-4"
@rendermode InteractiveAuto

<button @onclick="UpdateMessage">Click me</button> @message

@code {
    private string message = "Not updated yet.";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

위의 구성 요소를 로컬로 Blazor Web App사용하는 경우 클라이언트 프로젝트의 Pages 폴더에 구성 요소를 배치합니다. 클라이언트 프로젝트는 이름이 끝나는 솔루션의 프로젝트입니다 .Client. 앱이 실행 중이면 브라우저의 주소 표시줄로 이동합니다 /render-mode-4 .

렌더링 모드 전파

렌더링 모드는 구성 요소 계층 구조 아래로 전파됩니다.

렌더링 모드 적용 규칙:

• 기본 렌더링 모드는 Static입니다.
• 대화형 서버(InteractiveServer), Interactive WebAssembly(InteractiveWebAssembly) 및 대화형 자동(InteractiveAuto) 렌더링 모드는 형제 구성 요소에 대해 다른 렌더링 모드를 사용하는 것을 포함하여 구성 요소에서 사용할 수 있습니다.
• 자식 구성 요소에서는 다른 대화형 렌더링 모드로 전환할 수 없습니다. 예를 들어 서버 구성 요소는 WebAssembly 구성 요소의 자식일 수 없습니다.
• 정적 부모에서 대화형 자식 구성 요소에 전달된 매개 변수는 JSON 직렬화 가능해야 합니다. 즉, 정적 부모 구성 요소에서 대화형 자식 구성 요소로 렌더링 조각 또는 자식 콘텐츠를 전달할 수 없습니다.

다음 예제에서는 라우팅할 수 없는 페이지 SharedMessage 가 아닌 구성 요소를 사용합니다. 렌더링 모드에 구애 SharedMessage 받지 않는 구성 요소는 지시문이 있는 렌더링 모드를 @attribute 적용하지 않습니다. 이러한 시나리오를 Blazor Web App테스트하는 경우 앱의 Components 폴더에 다음 구성 요소를 배치합니다.

SharedMessage.razor:

<p>@Greeting</p>

<button @onclick="UpdateMessage">Click me</button> @message

<p>@ChildContent</p>

@code {
    private string message = "Not updated yet.";

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    [Parameter]
    public string Greeting { get; set; } = "Hello!";

    private void UpdateMessage()
    {
        message = "Somebody updated me!";
    }
}

렌더링 모드 상속

SharedMessage 구성 요소가 정적으로 렌더링된 부모 구성 요소에 배치되는 경우 구성 요소 SharedMessage 도 정적으로 렌더링되며 대화형이 아닙니다. 단추가 호출 UpdateMessage되지 않고 메시지가 업데이트되지 않습니다.

RenderMode5.razor:

@page "/render-mode-5"

<SharedMessage />

SharedMessage 구성 요소가 렌더링 모드를 정의하는 구성 요소에 배치되면 적용된 렌더링 모드를 상속합니다.

다음 예제 SharedMessage 에서 구성 요소는 클라이언트에 SignalR 대한 연결을 통해 대화형입니다. 단추가 호출 UpdateMessage되고 메시지가 업데이트됩니다.

RenderMode6.razor:

@page "/render-mode-6"
@rendermode InteractiveServer

<SharedMessage />

렌더링 모드가 다른 자식 구성 요소

다음 예제에서는 두 구성 요소가 모두 SharedMessage 미리 렌더링되고 페이지가 브라우저에 표시될 때 표시됩니다.

• 대화형 서버 쪽 렌더링(대화형 SSR)이 있는 첫 번째 SharedMessage 구성 요소는 회로가 SignalR 설정된 후 대화형입니다.
• CSR(클라이언트 쪽 렌더링)이 있는 두 번째 SharedMessage 구성 요소는 앱 번들이 다운로드되고 클라이언트에서 .NET 런타임이 활성화된 후 Blazor 대화형입니다.

RenderMode7.razor:

@page "/render-mode-7"

<SharedMessage @rendermode="InteractiveServer" />
<SharedMessage @rendermode="InteractiveWebAssembly" />

serialize할 수 있는 매개 변수가 있는 자식 구성 요소

다음 예제에서는 매개 변수를 사용하는 대화형 자식 구성 요소를 보여 줍니다. 매개 변수는 직렬화할 수 있어야 합니다.

RenderMode8.razor:

@page "/render-mode-8"

<SharedMessage @rendermode="InteractiveServer" Greeting="Welcome!" />

자식 콘텐츠 또는 렌더링 조각과 같은 직렬화할 수 없는 구성 요소 매개 변수는 지원되지 않습니다. 다음 예제에서는 자식 콘텐츠를 구성 요소에 SharedMessage 전달하면 런타임 오류가 발생합니다.

RenderMode9.razor:

@page "/render-mode-9"

<SharedMessage @rendermode="InteractiveServer">
    Child content
</SharedMessage>

❌오류:

System.InvalidOperationException: rendermode 'InteractiveServerRenderMode'를 사용하여 'ChildContent' 매개 변수를 구성 요소 'SharedMessage'에 전달할 수 없습니다. 매개 변수가 임의의 코드이며 serialize할 수 없는 대리자 형식 'Microsoft.AspNetCore.Components.RenderFragment'이기 때문입니다.

이전 제한을 피하려면 매개 변수가 없는 다른 구성 요소에 자식 구성 요소를 래핑합니다. 이는 구성 요소(Components/Routes.razor)를 사용하여 Routes 프로젝트 템플릿에서 Blazor Web App 구성 요소를 래핑 Router 하는 방법입니다.

WrapperComponent.razor:

<SharedMessage>
    Child content
</SharedMessage>

RenderMode10.razor:

@page "/render-mode-10"

<WrapperComponent @rendermode="InteractiveServer" />

앞의 예에서:

• 자식 콘텐츠는 런타임 오류를 생성하지 않고 구성 요소에 전달 SharedMessage 됩니다.
• SharedMessage 구성 요소는 서버에서 대화형으로 렌더링됩니다.

상위와 다른 렌더링 모드를 사용하는 자식 구성 요소

부모 렌더링 모드와 다른 대화형 렌더링 모드를 자식 구성 요소에 적용하지 마세요.

다음 구성 요소는 구성 요소가 렌더링될 때 런타임 오류가 발생합니다.

RenderMode11.razor:

@page "/render-mode-11"
@rendermode InteractiveServer

<SharedMessage @rendermode="InteractiveWebAssembly" />

❌오류:

Cannot create a component of type 'BlazorSample.Components.SharedMessage' because its render mode 'Microsoft.AspNetCore.Components.Web.InteractiveWebAssemblyRenderMode' is not supported by Interactive Server rendering.

전역 대화형 앱의 정적 SSR 페이지

앱의 사양에서 구성 요소가 정적 서버 쪽 렌더링(정적 SSR)을 채택하고 서버에서만 실행되도록 요구하는 경우 rest 와 앱에서 대화형 렌더링 모드를 사용하는 경우가 있습니다.

이 방법은 앱에 대화형 서버 또는 WebAssembly 렌더링을 사용할 수 없는 특정 페이지가 있는 경우에만 유용합니다. 예를 들어 HTTP 쿠키 읽기/쓰기에 의존하며 대화형 렌더링 대신 요청/응답 주기에서만 작동할 수 있는 페이지에 이 방법을 채택합니다. 대화형 렌더링을 사용하는 페이지의 경우 최종 사용자에게 덜 효율적이고 응답성이 떨어지기 때문에 정적 SSR 렌더링을 사용하도록 강요해서는 안 됩니다.

Razor 지시문과 함께 @attributeRazor 할당된 특성으로 [ExcludeFromInteractiveRouting] 구성 요소 페이지를 표시합니다.

@attribute [ExcludeFromInteractiveRouting]

특성을 적용하면 페이지 탐색이 대화형 라우팅에서 종료됩니다. 인바운드 탐색은 대화형 라우팅을 통해 페이지를 확인하는 대신 전체 페이지 다시 로드를 수행해야 합니다. 전체 페이지 다시 로드는 최상위 루트 구성 요소(일반적으로 App 구성 요소)App.razor가 서버에서 다시 렌더링되도록 하여 앱이 다른 최상위 렌더링 모드로 전환되도록 합니다.

RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting 확장 메서드를 사용하면 구성 요소가 특성이 [ExcludeFromInteractiveRouting] 현재 페이지에 적용되는지 여부를 검색할 수 있습니다.

구성 요소에서 App 다음 예제의 패턴을 사용합니다.

• 특성으로 [ExcludeFromInteractiveRouting] 주석이 추가되지 않은 페이지는 전역 대화형 작업을 사용하여 InteractiveServer 렌더링 모드로 기본값을 지정합니다. 다른 기본 전역 렌더링 모드로 InteractiveWebAssembly 바꾸 InteractiveServer 거나 InteractiveAuto 지정할 수 있습니다.
• 특성으로 주석이[ExcludeFromInteractiveRouting] 추가된 페이지는 정적 SSR(PageRenderMode할당됨null)을 채택합니다.

<!DOCTYPE html>
<html>
<head>
    ...
    <HeadOutlet @rendermode="@PageRenderMode" />
</head>
<body>
    <Routes @rendermode="@PageRenderMode" />
    ...
</body>
</html>

@code {
    [CascadingParameter]
    private HttpContext HttpContext { get; set; } = default!;

    private IComponentRenderMode? PageRenderMode
        => HttpContext.AcceptsInteractiveRouting() ? InteractiveServer : null;
}

확장 메서드를 RazorComponentsEndpointHttpContextExtensions.AcceptsInteractiveRouting 사용하는 대안은 .를 사용하여 HttpContext.GetEndpoint()?.Metadata수동으로 엔드포인트 메타데이터를 읽는 것입니다.

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

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

예를 들어 전역 Interactive WebAssembly 또는 대화형 자동 렌더링을 사용하는 Blazor Web App 프로젝트에서 다음 Home 구성 요소를 .Client 고려합니다. 구성 요소는 환경의 이름을 얻기 위해 삽입 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 서버에 등록된 서비스가 아니기 때문에 발생합니다.

미리 렌더링하는 동안 앱에 값이 필요하지 않은 경우 서비스 유형 자체 대신 서비스를 가져오기 위해 삽입하여 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;
        }
    }
}

그러나 미리 렌더링하는 동안 논리에 값이 필요한 경우에는 이전 방법이 유용하지 않습니다.

구성 요소에 대한 미리 렌더링을 사용하지 않도록 설정하는 경우에도 문제를 방지할 수 있지만, 이는 구성 요소의 사양을 충족하지 못할 수 있는 많은 경우에 수행해야 하는 극단적인 조치입니다.

이 시나리오를 해결하기 위해 수행할 수 있는 세 가지 방법이 있습니다. 다음은 가장 권장되는 항목부터 최소 권장 항목까지 나열됩니다.

• 공유 프레임워크 서비스에 권장 됨: 주 프로젝트에 서버 쪽이 등록되지 않은 공유 프레임워크 서비스의 경우 기본 프로젝트에 서비스를 등록하여 미리 렌더링하는 동안 사용할 수 있도록 합니다. 이 시나리오의 예제는 ASP.NET Core 앱에서 웹 API 호출의 서비스에 대한 HttpClient 지침을 참조하세요.Blazor

• 공유 프레임워크 외부의 서비스에 권장 됨: 서버에서 서비스에 대한 사용자 지정 서비스 구현을 만듭니다. 프로젝트의 대화형 구성 요소 .Client 에서 일반적으로 서비스를 사용합니다. 이 방법의 데모는 ASP.NET Core Blazor 환경을 참조하세요.

• 서비스 추상화 만들기 및 서버 프로젝트에서 서비스에 대한 구현을 .Client 만듭니다. 각 프로젝트에 서비스를 등록합니다. 구성 요소에 사용자 지정 서비스를 삽입합니다.

• 서버 쪽 패키지에 프로젝트 패키지 참조를 추가하고 .Client 서버에서 미리 렌더링할 때 서버 쪽 API 사용으로 대체될 수 있습니다.

추가 어셈블리에서 구성 요소 검색

참조된 Blazor 프로젝트에서 라우팅 가능한 Razor 구성 요소를 검색하려면 프레임워크에 추가 어셈블리를 공개해야 합니다. 자세한 내용은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

대화형 서버 구성 요소가 남아 있지 않은 경우 회로가 닫히기

대화형 서버 구성 요소는 회로라는 브라우저와 실시간 연결을 사용하여 웹 UI 이벤트를 처리합니다. 루트 대화형 서버 구성 요소가 렌더링될 때 회로 및 연결된 상태가 만들어집니다. 페이지에 남아 있는 대화형 서버 구성 요소가 없으면 회로가 닫혀 서버 리소스를 확보합니다.

사용자 지정 약식 렌더링 모드

지시문은 @rendermode 형식 IComponentRenderMode의 정적 인스턴스인 단일 매개 변수를 사용합니다. 지시문 특성은 @rendermode 정적 또는 그렇지 않은 렌더링 모드 인스턴스를 사용할 수 있습니다. 프레임워크는 Blazor 정적 클래스에 RenderMode 편의를 위해 미리 정의된 렌더링 모드를 제공하지만 직접 만들 수 있습니다.

일반적으로 구성 요소는 다음 @rendermode 지시문을 사용하여 미리 렌더링을 사용하지 않도록 설정합니다.

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

그러나 앱 _Imports 의 파일(Components/_Imports.razor)을 통해 미리 렌더링하지 않고 약식 대화형 서버 쪽 렌더링 모드를 만드는 다음 예제를 고려하세요.

public static IComponentRenderMode InteractiveServerWithoutPrerendering { get; } = 
    new InteractiveServerRenderMode(prerender: false);

폴더 전체의 구성 요소에서 약식 렌더링 모드를 Components 사용합니다.

@rendermode InteractiveServerWithoutPrerendering

또는 단일 구성 요소 인스턴스가 프라이빗 필드를 통해 사용자 지정 렌더링 모드를 정의할 수 있습니다.

@rendermode interactiveServerWithoutPrerendering

...

@code {
    private static IComponentRenderMode interactiveServerWithoutPrerendering = 
        new InteractiveServerRenderMode(prerender: false);
}

현재 약식 렌더링 모드 접근 방식은 플래그 지정 prerender 의 자세한 정도를 줄이는 데만 유용할 수 있습니다. 대화형 렌더링에 추가 플래그를 사용할 수 있게 되고 서로 다른 플래그 조합으로 약식 렌더링 모드를 만들려는 경우 나중에 약식 방법이 더 유용할 수 있습니다.

최상위 가져오기 파일을 통한 서비스 주입(_Imports.razor)

이 섹션은 s에 Blazor Web App만 적용됩니다.

폴더()의 Components 최상위 가져오기 파일은 해당 참조를 구성 요소(Components/_Imports.razorApp.razor)를 포함하는 폴더 계층 구조의 모든 구성 요소에 App 삽입합니다. App 페이지 구성 요소의 미리 렌더링을 사용하지 않도록 설정하더라도 구성 요소는 항상 정적으로 렌더링됩니다. 따라서 최상위 가져오기 파일을 통해 서비스를 삽입하면 페이지 구성 요소에서 서비스의 두 인스턴스가 확인됩니다.

이 시나리오를 해결하려면 폴더(Components/Pages/_Imports.razor)에 배치된 Pages 새 가져오기 파일에 서비스를 삽입합니다. 해당 위치에서 서비스는 페이지 구성 요소에서 한 번만 확인됩니다.

추가 리소스

• WebSocket 압축
  • ASP.NET Core BlazorSignalR 지침
  • ASP.NET Core Blazor 대화형 서버 쪽 렌더링에 대한 위협 완화 지침
• 정적 서버 쪽 렌더링을 사용하여 Core Blazor JavaScript ASP.NET(정적 SSR)
• 연계 값/매개 변수 및 렌더링 모드 경계: 또한 문서의 앞부분에 있는 루트 수준 연계 매개 변수 섹션을 참조하세요.
• 정적 서버 쪽 렌더링(정적 SSR)을 사용하는 ASP.NET Core Razor 클래스 라이브러리(RCL)