ASP.NET Core의 구성 요소 태그 도우미

구성 요소 태그 도우미는 페이지 페이지 또는 MVC 보기에서 Razor 구성 요소를 렌더링 Razor 합니다.

필수 조건

ASP.NET Core 구성 요소를 ASP.NET Core Razor 앱에 통합 문서의 페이지 또는 보기 섹션에서 라우팅할 수 없는 구성 요소 사용 문서의 지침을 따릅니다.

다음의 경우 구성 섹션의 지침을 따릅니다.

  • Blazor Server: 라우팅 가능 및 라우팅 불가능 Razor 구성 요소를 Razor Pages 및 MVC 앱에 통합합니다.
  • Blazor WebAssembly: 호스트된 Blazor WebAssembly 솔루션의 Razor 구성 요소를 Razor Pages 및 MVC 앱에 통합합니다.

Prerender의 구성 섹션에 있는 지침을 따르고 ASP.NET Core Razor 구성 요소 문서를 통합합니다.

구성 요소 태그 도우미

페이지 또는 보기에서 구성 요소를 렌더링하려면 구성 요소 태그 도우미(<component> 태그)를 사용합니다.

참고 항목

호스팅된 Blazor WebAssembly 앱에서 Razor 구성 요소를 Razor Pages 및 MVC 앱에 통합하는 기능은 .NET 5.0 이상의 ASP.NET Core에서 지원됩니다.

RenderMode는 구성 요소에 대해 다음을 구성합니다.

  • 페이지에 미리 렌더링할지 여부
  • 페이지에 정적 HTML로 렌더링할지 여부 또는 사용자 에이전트에서 Blazor 앱을 부트스트랩하는 데 필요한 정보를 포함할지 여부

Blazor WebAssembly 앱 렌더링 모드가 다음 표에 나와 있습니다.

렌더링 모드 설명
WebAssembly 브라우저에 로드될 때 대화형 구성 요소를 포함하는 데 사용할 Blazor WebAssembly 앱의 마커를 렌더링합니다. 구성 요소는 미리 렌더링되지 않습니다. 이 옵션을 사용하면 다양한 Blazor WebAssembly 구성 요소를 서로 다른 페이지에서 쉽게 렌더링할 수 있습니다.
WebAssemblyPrerendered 구성 요소를 정적 HTML로 미리 렌더링하고 나중에 브라우저에서 로드될 때 구성 요소를 대화형으로 만드는 데 사용할 수 있도록 Blazor WebAssembly 앱의 마커를 포함합니다.

렌더링 모드는 다음 표에 나와 있습니다.

렌더링 모드 설명
ServerPrerendered 구성 요소를 정적 HTML로 렌더링하고 서버 쪽 Blazor 앱에 대한 표식을 포함합니다. 사용자 에이전트를 시작할 때 이 표식은 Blazor 앱을 부트스트랩하는 데 사용됩니다.
Server 서버 쪽 Blazor 앱에 대한 마커를 렌더링합니다. 구성 요소의 출력은 포함되지 않습니다. 사용자 에이전트를 시작할 때 이 표식은 Blazor 앱을 부트스트랩하는 데 사용됩니다.
Static 구성 요소를 정적 HTML에 렌더링합니다.

앱 렌더링 모드는 다음 표에 나와 있습니다.

렌더링 모드 설명
ServerPrerendered 구성 요소를 정적 HTML로 렌더링하고 서버 쪽 Blazor 앱에 대한 표식을 포함합니다. 사용자 에이전트를 시작할 때 이 표식은 Blazor 앱을 부트스트랩하는 데 사용됩니다.
Server 서버 쪽 Blazor 앱에 대한 마커를 렌더링합니다. 구성 요소의 출력은 포함되지 않습니다. 사용자 에이전트를 시작할 때 이 표식은 Blazor 앱을 부트스트랩하는 데 사용됩니다.
Static 구성 요소를 정적 HTML에 렌더링합니다.

추가 특성에는 다음이 포함됩니다.

  • 여러 Razor 구성 요소를 렌더링하는 여러 구성 요소 태그 도우미가 허용됩니다.
  • 앱이 시작된 후에는 구성 요소를 동적으로 렌더링할 수 없습니다.
  • 페이지와 뷰는 구성 요소를 사용할 수 있지만 반대의 경우는 지원되지 않습니다. 구성 요소는 부분 보기 및 섹션과 같은 보기 및 페이지 특정 시나리오를 사용할 수 없습니다. 구성 요소에서 부분 보기의 논리를 사용하려면 부분 보기 논리를 구성 요소로 추출합니다.
  • 정적 HTML 페이지에서 서버 구성 요소를 렌더링할 수는 없습니다.

다음 구성 요소 태그 도우미는 다음을 EmbeddedCounter 사용하여 서버 쪽 Blazor 앱 ServerPrerendered의 페이지 또는 보기에서 구성 요소를 렌더링합니다.

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />

앞의 예제에서는 구성 요소가 앱의 Components 폴더에 있다고 가정 EmbeddedCounter 합니다. 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: @using BlazorSample.Components).

구성 요소 태그 도우미는 구성 요소에 매개 변수를 전달할 수도 있습니다. 검사box 레이블의 색과 크기를 설정하는 다음 ColorfulCheckbox 구성 요소를 고려합니다.

Components/ColorfulCheckbox.razor:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string? Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

Size(int) 및 Color(string) 구성 요소 매개 변수는 구성 요소 태그 도우미를 통해 설정할 수 있습니다.

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

앞의 예제에서는 구성 요소가 폴더에 있다고 ColorfulCheckbox 가정합니다 Components . 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: @using BlazorSample.Components).

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared

...

<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />

앞의 예제에서는 구성 요소가 앱의 Shared 폴더에 있다고 가정 EmbeddedCounter 합니다. 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: 호스팅된 Blazor 솔루션의 @using BlazorSample.Shared 또는 @using BlazorSample.Client.Shared).

구성 요소 태그 도우미는 구성 요소에 매개 변수를 전달할 수도 있습니다. 검사box 레이블의 색과 크기를 설정하는 다음 ColorfulCheckbox 구성 요소를 고려합니다.

Shared/ColorfulCheckbox.razor:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string? Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

Size(int) 및 Color(string) 구성 요소 매개 변수는 구성 요소 태그 도우미를 통해 설정할 수 있습니다.

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Shared

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

앞의 예제에서는 구성 요소가 폴더에 있다고 ColorfulCheckbox 가정합니다 Shared . 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: @using BlazorSample.Shared).

다음 HTML은 페이지 또는 보기에서 렌더링됩니다.

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

앞의 예제에서 param-Color와 같이 따옴표 붙은 문자열을 전달하려면 명시적 Razor 식이 필요합니다. 특성이 object 형식이기 때문에 string 형식 값에 대한 Razor 구문 분석 동작은 param-* 특성에 적용되지 않습니다.

다음을 제외한 모든 형식의 매개 변수가 지원됩니다.

  • 제네릭 매개 변수.
  • 직렬화할 수 없는 매개 변수.
  • 컬렉션 매개 변수의 상속.
  • 형식이 Blazor WebAssembly 앱 외부에서 또는 지연 로드된 어셈블리 내에서 정의된 매개 변수.
  • 자식 콘텐츠에 대한 RenderFragment 대리자를 수신하는 경우(예: param-ChildContent="..."). 이 시나리오에서는 전달하려는 자식 콘텐츠로 렌더링하고자 하는 구성 요소를 참조하는 Razor 구성 요소(.razor)를 만든 다음 구성 요소 태그 도우미를 사용하여 페이지 또는 보기에서 Razor 구성 요소를 호출하는 것이 좋습니다.

매개 변수 형식은 JSON 직렬화 가능해야 하며, 이는 일반적으로 형식에 기본 생성자와 설정 가능한 속성이 있어야 함을 의미합니다. 예를 들어 SizeColor의 형식이 JSON 직렬 변환기에서 지원되는 기본 형식(intstring)이기 때문에 앞의 예제에서 SizeColor 값을 지정할 수 있습니다.

다음 예제에서는 클래스 개체가 구성 요소에 전달됩니다.

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

클래스에는 공용 매개 변수가 없는 생성자가 있어야 합니다.

Components/ParameterComponent.razor:

<h2>ParameterComponent</h2>

<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>

@code
{
    [Parameter]
    public MyClass? MyObject { get; set; }
}

Pages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Components

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

앞의 예제에서는 구성 요소가 앱의 Components 폴더에 있다고 가정 ParameterComponent 합니다. 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: @using BlazorSample@using BlazorSample.Components). MyClass는 앱의 네임스페이스에 있습니다.

Shared/ParameterComponent.razor:

<h2>ParameterComponent</h2>

<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>

@code
{
    [Parameter]
    public MyClass? MyObject { get; set; }
}

Pages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Shared

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

앞의 예제에서는 구성 요소가 앱의 Shared 폴더에 있다고 가정 ParameterComponent 합니다. 자리 표시자 {APP ASSEMBLY}는 앱의 어셈블리 이름입니다(예: @using BlazorSample@using BlazorSample.Shared). MyClass는 앱의 네임스페이스에 있습니다.

추가 리소스