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

아티클
2025-05-05

태그 도우미 구성 요소는 서버 쪽 코드에서 HTML 요소를 조건부로 수정하거나 추가할 수 있는 태그 도우미입니다. 이 기능은 ASP.NET Core 2.0 이상에서 사용할 수 있습니다.

ASP.NET Core에는 두 가지 기본 제공 태그 도우미 구성 요소가 포함됩니다. headbody 네임스페이스에 Microsoft.AspNetCore.Mvc.Razor.TagHelpers 있으며 MVC와 Razor Pages 모두에서 사용할 수 있습니다. 태그 도우미 구성 요소에는 앱 _ViewImports.cshtml등록이 필요하지 않습니다.

샘플 코드 보기 및 다운로드(다운로드 방법)

사용 사례

태그 도우미 구성 요소의 두 가지 일반적인 사용 사례는 다음과 같습니다.

<link>를 <head>에 삽입합니다.
<body>에 <script>를 삽입합니다.

다음 섹션에서는 이러한 사용 사례를 설명합니다.

HTML 헤드 요소에 삽입

HTML <head> 요소 내에서 CSS 파일은 일반적으로 HTML <link> 요소와 함께 가져옵니다. 다음 코드는 head 태그 도우미 구성 요소를 사용하여 <head> 요소에 <link> 요소를 삽입합니다.

using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace RazorPagesSample.TagHelpers
{
    public class AddressStyleTagHelperComponent : TagHelperComponent
    {
        private readonly string _style = 
            @"<link rel=""stylesheet"" href=""/css/address.css"" />";

        public override int Order => 1;

        public override Task ProcessAsync(TagHelperContext context,
                                          TagHelperOutput output)
        {
            if (string.Equals(context.TagName, "head", 
                              StringComparison.OrdinalIgnoreCase))
            {
                output.PostContent.AppendHtml(_style);
            }

            return Task.CompletedTask;
        }
    }
}

앞의 코드에서 다음을 수행합니다.

AddressStyleTagHelperComponent는 TagHelperComponent를 구현합니다. 추상화:
- 를 사용하여 클래스를 초기화할 수 있습니다 TagHelperContext.
- 태그 도우미 구성 요소를 사용하여 HTML 요소를 추가하거나 수정할 수 있습니다.
이 속성은 Order 구성 요소가 렌더링되는 순서를 정의합니다. Order 는 앱에서 태그 도우미 구성 요소를 여러 가지 사용하는 경우에 필요합니다.
ProcessAsync는 실행 컨텍스트의 TagName 속성 값을 head와 비교합니다. 비교가 true로 평가되면 필드의 _style 내용이 HTML <head> 요소에 삽입됩니다.

HTML 본문 요소에 삽입

body 태그 도우미 구성 요소는 <body> 요소에 <script> 요소를 삽입할 수 있습니다. 다음 코드는 이 기술을 보여 줍니다.

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace RazorPagesSample.TagHelpers
{
    public class AddressScriptTagHelperComponent : TagHelperComponent
    {
        public override int Order => 2;
        
        public override async Task ProcessAsync(TagHelperContext context,
                                                TagHelperOutput output)
        {
            if (string.Equals(context.TagName, "body",
                              StringComparison.OrdinalIgnoreCase))
            {
                var script = await File.ReadAllTextAsync(
                    "TagHelpers/Templates/AddressToolTipScript.html");
                output.PostContent.AppendHtml(script);
            }
        }
    }
}

요소를 저장하는 <script> 데 별도의 HTML 파일이 사용됩니다. HTML 파일을 사용하면 코드를 더 깨끗하고 더 쉽게 유지 관리할 수 있습니다. 앞의 TagHelpers/Templates/AddressToolTipScript.html 코드는 해당 내용을 읽고 태그 도우미 출력과 함께 추가합니다. 파일에는 다음의 AddressToolTipScript.html 태그가 포함됩니다.

<script>
$("address[printable]").hover(function() {
    $(this).attr({
        "data-toggle": "tooltip",
        "data-placement": "right",
        "title": "Home of Microsoft!"
    });
});
</script>

앞의 코드는 부트스트랩 도구 설명 위젯을 포함된 printable 속성의 모든 <address> 요소에 바인딩합니다. 마우스 포인터가 요소 위로 마우스를 가져가면 효과가 표시됩니다.

구성 요소 등록

태그 도우미 구성 요소는 앱의 태그 도우미 구성 요소 컬렉션에 추가해야 합니다. 컬렉션에 추가하는 세 가지 방법이 있습니다.

서비스 컨테이너를 통한 등록
파일을 통한 Razor 등록
페이지 모델 또는 컨트롤러를 통한 등록

서비스 컨테이너를 통한 등록

태그 도우미 구성 요소 클래스가 ITagHelperComponentManager관리되지 않는 경우 DI(종속성 주입) 시스템에 등록해야 합니다. 다음 Startup.ConfigureServices 코드는 AddressStyleTagHelperComponent 및 AddressScriptTagHelperComponent 클래스를 임시 수명으로 등록합니다.

public void ConfigureServices(IServiceCollection services)
{
    services.Configure<CookiePolicyOptions>(options =>
    {
        options.CheckConsentNeeded = context => true;
        options.MinimumSameSitePolicy = SameSiteMode.None;
    });

    services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

    services.AddTransient<ITagHelperComponent, 
        AddressScriptTagHelperComponent>();
    services.AddTransient<ITagHelperComponent, 
        AddressStyleTagHelperComponent>();
}

파일을 통한 Razor 등록

태그 도우미 구성 요소가 DI에 등록되지 않은 경우 Razor 페이지 또는 MVC 보기에서 등록할 수 있습니다. 이 기술은 Razor 파일에서 삽입된 태그 및 구성 요소의 실행 순서를 제어하는 데 사용됩니다.

ITagHelperComponentManager 태그 도우미 구성 요소를 추가하거나 앱에서 제거하는 데 사용됩니다. 다음 코드는 AddressTagHelperComponent를 사용하여 이 기술을 보여 줍니다.

@using RazorPagesSample.TagHelpers;
@using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
@inject ITagHelperComponentManager manager;

@{
    string markup;

    if (Model.IsWeekend)
    {
        markup = "<em class='text-warning'>Office closed today!</em>";
    }
    else
    {
        markup = "<em class='text-info'>Office open today!</em>";
    }

    manager.Components.Add(new AddressTagHelperComponent(markup, 1));
}

앞의 코드에서 다음을 수행합니다.

지시문은 @inject의 ITagHelperComponentManager 인스턴스를 제공합니다. 인스턴스는 나중에 Razor 파일에서 액세스하기 위해 manager 변수에 할당됩니다.
인스턴스 AddressTagHelperComponent 가 앱의 태그 도우미 구성 요소 컬렉션에 추가됩니다.

`AddressTagHelperComponent는 markup 및 order 매개 변수를 허용하는 생성자를 수용하도록 수정됩니다.`

private readonly string _markup;

public override int Order { get; }

public AddressTagHelperComponent(string markup = "", int order = 1)
{
    _markup = markup;
    Order = order;
}

제공된 markup 매개 변수는 다음과 같이 사용됩니다 ProcessAsync .

public override async Task ProcessAsync(TagHelperContext context,
                                        TagHelperOutput output)
{
    if (string.Equals(context.TagName, "address",
            StringComparison.OrdinalIgnoreCase) &&
        output.Attributes.ContainsName("printable"))
    {
        TagHelperContent childContent = await output.GetChildContentAsync();
        string content = childContent.GetContent();
        output.Content.SetHtmlContent(
            $"<div>{content}<br>{_markup}</div>{_printableButton}");
    }
}

페이지 모델 또는 컨트롤러를 통한 등록

태그 도우미 구성 요소가 DI에 등록되지 않은 경우 Razor 페이지 모델 또는 MVC 컨트롤러에서 등록할 수 있습니다. 이 기술은 C# 논리를 파일에서 Razor 분리하는 데 유용합니다.

생성자 주입은 .의 ITagHelperComponentManager인스턴스에 액세스하는 데 사용됩니다. 태그 도우미 구성 요소는 인스턴스의 태그 도우미 구성 요소 컬렉션에 추가됩니다. 다음 Razor 페이지 모델은 이 기술을 AddressTagHelperComponent를 사용하여 보여 줍니다.

using System;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using Microsoft.AspNetCore.Mvc.RazorPages;
using RazorPagesSample.TagHelpers;

public class IndexModel : PageModel
{
    private readonly ITagHelperComponentManager _tagHelperComponentManager;

    public bool IsWeekend
    {
        get
        {
            var dayOfWeek = DateTime.Now.DayOfWeek;

            return dayOfWeek == DayOfWeek.Saturday ||
                   dayOfWeek == DayOfWeek.Sunday;
        }
    }

    public IndexModel(ITagHelperComponentManager tagHelperComponentManager)
    {
        _tagHelperComponentManager = tagHelperComponentManager;
    }

    public void OnGet()
    {
        string markup;

        if (IsWeekend)
        {
            markup = "<em class='text-warning'>Office closed today!</em>";
        }
        else
        {
            markup = "<em class='text-info'>Office open today!</em>";
        }

        _tagHelperComponentManager.Components.Add(
            new AddressTagHelperComponent(markup, 1));
    }
}

앞의 코드에서 다음을 수행합니다.

생성자 주입은 .의 ITagHelperComponentManager인스턴스에 액세스하는 데 사용됩니다.
인스턴스 AddressTagHelperComponent 가 앱의 태그 도우미 구성 요소 컬렉션에 추가됩니다.

구성 요소 만들기

사용자 지정 태그 도우미 구성 요소를 만들려면 다음을 수행합니다.

에서 TagHelperComponentTagHelper파생되는 공용 클래스를 만듭니다.
클래스에 [HtmlTargetElement] 특성을 적용합니다. 대상 HTML 요소의 이름을 지정합니다.
선택 사항: 클래스에 특성 [EditorBrowsable(EditorBrowsableState.Never)] 을 적용하여 IntelliSense에서 형식의 표시를 억제합니다.

다음 코드는 <address> HTML 요소를 대상으 로 하는 사용자 지정 태그 도우미 구성 요소를 생성합니다.

using System.ComponentModel;
using Microsoft.AspNetCore.Mvc.Razor.TagHelpers;
using Microsoft.AspNetCore.Razor.TagHelpers;
using Microsoft.Extensions.Logging;

namespace RazorPagesSample.TagHelpers
{
    [HtmlTargetElement("address")]
    [EditorBrowsable(EditorBrowsableState.Never)]
    public class AddressTagHelperComponentTagHelper : TagHelperComponentTagHelper
    {
        public AddressTagHelperComponentTagHelper(
            ITagHelperComponentManager componentManager, 
            ILoggerFactory loggerFactory) : base(componentManager, loggerFactory)
        {
        }
    }
}

사용자 지정 address 태그 도우미 구성 요소를 사용하여 다음과 같이 HTML 태그를 삽입합니다.

public class AddressTagHelperComponent : TagHelperComponent
{
    private readonly string _printableButton =
        "<button type='button' class='btn btn-info' onclick=\"window.open(" +
        "'https://binged.it/2AXRRYw')\">" +
        "<span class='glyphicon glyphicon-road' aria-hidden='true'></span>" +
        "</button>";

    public override int Order => 3;

    public override async Task ProcessAsync(TagHelperContext context,
                                            TagHelperOutput output)
    {
        if (string.Equals(context.TagName, "address",
                StringComparison.OrdinalIgnoreCase) &&
            output.Attributes.ContainsName("printable"))
        {
            var content = await output.GetChildContentAsync();
            output.Content.SetHtmlContent(
                $"<div>{content.GetContent()}</div>{_printableButton}");
        }
    }
}

앞의 ProcessAsync 메서드는 제공된 HTML을 일치하는 <address> 요소에 삽입합니다. 주입은 다음과 같은 경우에 발생합니다.

실행 컨텍스트의 TagName 속성 값은 같습니다 address.
해당 <address> 요소에 특성이 있습니다 printable .

예를 들어, <address> 요소를 처리할 때 if 문이 true로 평가됩니다.

<address printable>
    One Microsoft Way<br />
    Redmond, WA 98052-6399<br />
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

다음을 통해 공유

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

사용 사례

HTML 헤드 요소에 삽입

HTML 본문 요소에 삽입

구성 요소 등록

서비스 컨테이너를 통한 등록

파일을 통한 Razor 등록

페이지 모델 또는 컨트롤러를 통한 등록

구성 요소 만들기

추가 리소스

추가 리소스