ASP.NET Core의 부분 보기

아티클
11/30/2023

작성자: Steve Smith, Maher JENDOUBI, Rick Anderson 및 Scott Sauber

부분 보기는 Razor 다른 태그 파일의 렌더링된 출력 내에서 HTML 출력을 @page 렌더링하는 지시문이 없는 태그 파일(.cshtml)입니다.

부분 보기라는 용어는 MVC 앱(태그 파일을 보기라고 부름) 또는 Razor Pages 앱(태그 파일을 페이지라고 부름)을 개발할 때 사용됩니다. 이 항목에서는 일반적으로 MVC 보기 및 Razor Pages 페이지를 태그 파일이라고 부릅니다.

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

부분 보기를 사용하는 경우

부분 보기는 다음을 수행하는 효과적인 방법입니다.

큰 태그 파일을 작은 구성 요소로 나눕니다.

여러 개의 논리적 부분으로 구성된 크고 복잡한 태그 파일은 부분 보기로 분리된 각 부분으로 작업하는 것이 유용합니다. 태그에는 전체 페이지 구조와 부분 보기에 대한 참조만 포함되므로 태그 파일의 코드를 관리하기가 쉽습니다.
태그 파일들 간의 공통 태그 콘텐츠 중복을 줄입니다.

태그 파일들 간에 동일한 태그 요소가 사용될 때 부분 보기가 태그 콘텐츠의 중복을 하나의 부분 보기 파일로 제거합니다. 부분 보기에서 태그가 변경되면 부분 보기를 사용하는 태그 파일들의 렌더링된 출력이 수정됩니다.

공통 레이아웃 요소를 유지 관리하기 위해서 부분 보기를 사용해서는 안 됩니다. 공통 레이아웃 요소는 _Layout.cshtml 파일에 지정해야 합니다.

태그를 렌더링하기 위해 복잡한 렌더링 논리 또는 코드 실행이 필요한 경우 부분 보기를 사용하지 마세요. 부분 보기 대신 보기 구성 요소를 사용합니다.

부분 보기 선언

부분 보기는 Views 폴더(MVC) 또는 Pages 폴더(Razor Pages) 내에서 유지 관리되는 @page 지시문이 없는 .cshtml 태그 파일입니다.

ASP.NET Core MVC에서 컨트롤러의 ViewResult는 보기 또는 부분 보기를 반환할 수 있습니다. Razor 페이지에서 PageModel은 PartialViewResult 개체로 표시되는 부분 보기를 반환할 수 있습니다. 부분 보기 참조 및 렌더링은 부분 보기 참조 섹션에 설명되어 있습니다.

MVC 보기 또는 페이지 렌더링과 달리 부분 보기는 실행 _ViewStart.cshtml되지 않습니다. _ViewStart.cshtml에 대한 자세한 내용은 ASP.NET Core의 레이아웃을 참조하세요.

부분 보기 파일 이름은 종종 밑줄(_)로 시작됩니다. 이 명명 규칙은 필수는 아니지만 부분 보기를 보기 및 페이지와 시각적으로 구분하는 데 도움이 됩니다.

부분 보기는 .cshtml Views 폴더 내에 기본 태그 파일입니다.

컨트롤러의 ViewResult는 보기 또는 부분 보기를 반환할 수 있습니다. 부분 보기 참조 및 렌더링은 부분 보기 참조 섹션에 설명되어 있습니다.

MVC 뷰 렌더링과 달리 부분 보기는 실행 _ViewStart.cshtml되지 않습니다. _ViewStart.cshtml에 대한 자세한 내용은 ASP.NET Core의 레이아웃을 참조하세요.

부분 보기 파일 이름은 종종 밑줄(_)로 시작됩니다. 이 명명 규칙은 필수는 아니지만 부분 보기를 보기와 시각적으로 구분하는 데 도움이 됩니다.

부분 보기 참조

Razor Pages PageModel에서 부분 보기 사용

ASP.NET Core 2.0 또는 2.1에서 다음 처리기 메서드는 응답으로 _AuthorPartialRP.cshtml 부분 보기를 렌더링합니다.

public IActionResult OnGetPartial() =>
    new PartialViewResult
    {
        ViewName = "_AuthorPartialRP",
        ViewData = ViewData,
    };

ASP.NET Core 2.2 이상에서 처리기 메서드는 Partial 메서드를 대신 호출하여 PartialViewResult 개체를 생성할 수 있습니다.

public IActionResult OnGetPartial() =>
    Partial("_AuthorPartialRP");

태그 파일에서 부분 보기 사용

태그 파일 내에서 부분 보기를 참조할 수 있는 여러 가지 방법이 있습니다. 앱에서 다음과 같은 비동기 렌더링 방법 중 하나를 사용하는 것이 좋습니다.

부분 태그 도우미
비동기 HTML 도우미

태그 파일 내에서 부분 보기를 참조할 수 있는 두 가지 방법이 있습니다.

비동기 HTML 도우미
동기 HTML 도우미

앱에서 비동기 HTML 도우미를 사용하는 것이 좋습니다.

부분 태그 도우미

부분 태그 도우미에는 ASP.NET Core 2.1 이상이 필요합니다.

부분 태그 도우미는 콘텐츠를 비동기식으로 렌더링하며 HTML과 비슷한 구문을 사용합니다.

<partial name="_PartialName" />

파일 확장자가 있는 경우 태그 도우미는 부분 보기를 호출하는 태그 파일과 동일한 폴더에 있어야 하는 부분 보기를 참조합니다.

<partial name="_PartialName.cshtml" />

다음 예제에서는 앱 루트의 부분 보기를 참조합니다. 물결표-슬래시(~/) 또는 슬래시(/)로 시작되는 경로는 앱 루트를 참조합니다.

Razor Pages

<partial name="~/Pages/Folder/_PartialName.cshtml" />
<partial name="/Pages/Folder/_PartialName.cshtml" />

MVC

<partial name="~/Views/Folder/_PartialName.cshtml" />
<partial name="/Views/Folder/_PartialName.cshtml" />

다음 예제는 상대 경로가 있는 부분 보기를 참조합니다.

<partial name="../Account/_PartialName.cshtml" />

자세한 내용은 ASP.NET Core의 부분 태그 도우미를 참조하세요.

비동기 HTML 도우미

HTML 도우미를 사용할 때 가장 좋은 방법은 PartialAsync를 사용하는 것입니다. PartialAsync는 Task<TResult>에 래핑된 IHtmlContent 형식을 반환합니다. 이 메서드는 대기된 호출에 접두사로 @ 문자를 사용하여 참조합니다.

@await Html.PartialAsync("_PartialName")

파일 확장자가 있는 경우 HTML 도우미는 부분 보기를 호출하는 태그 파일과 동일한 폴더에 있어야 하는 부분 보기를 참조합니다.

@await Html.PartialAsync("_PartialName.cshtml")

다음 예제에서는 앱 루트의 부분 보기를 참조합니다. 물결표-슬래시(~/) 또는 슬래시(/)로 시작되는 경로는 앱 루트를 참조합니다.

Razor Pages

@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")

MVC

@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")

다음 예제는 상대 경로가 있는 부분 보기를 참조합니다.

@await Html.PartialAsync("../Account/_LoginPartial.cshtml")

또는 RenderPartialAsync를 사용하여 부분 보기를 렌더링할 수 있습니다. 이 메서드는 IHtmlContent를 반환하지 않습니다. 렌더링된 출력을 응답에 직접 스트리밍합니다. 이 메서드는 결과를 반환하지 않기 때문에 Razor 코드 블록 내에서 호출되어야 합니다.

@{
    await Html.RenderPartialAsync("_AuthorPartial");
}

RenderPartialAsync 스트림은 콘텐츠를 렌더링했으므로 일부 시나리오에서 더 나은 성능을 제공합니다. 성능이 중요한 상황에서는 두 가지 방법을 모두 사용하여 페이지를 벤치마크하고 빠른 응답을 생성하는 방법을 사용합니다.

동기 HTML 도우미

Partial 및 RenderPartial은 각각 PartialAsync 및 RenderPartialAsync에 해당하는 동기 항목입니다. 교착 상태가 발생하는 시나리오가 있으므로 동기 해당 항목은 사용하지 않는 것이 좋습니다. 동기 메서드는 이후 릴리스에서 제거 대상으로 지정되었습니다.

Important

코드를 실행해야 하는 경우 부분 보기 대신 보기 구성 요소를 사용하세요.

Partial 또는 RenderPartial 호출 시 Visual Studio 분석기 경고가 발생합니다. 예를 들어 Partial의 존재는 다음 경고 메시지를 생성합니다.

IHtmlHelper.Partial 사용 시 애플리케이션이 교착 상태가 될 수 있습니다. <부분> 태그 도우미 또는 IHtmlHelper.PartialAsync를 사용하세요.

@Html.Partial 호출을 @await Html.PartialAsync 또는 부분 태그 도우미로 바꿉니다. 부분 태그 도우미 마이그레이션에 대한 자세한 내용은 HTML 도우미에서 마이그레이션을 참조합니다.

부분 보기 검색

파일 확장자 없는 이름으로 부분 보기를 참조하는 경우, 다음 위치가 명시된 순서로 검색됩니다.

Razor Pages

현재 실행 중인 페이지의 폴더
페이지의 폴더 위에 있는 디렉터리 그래프
/Shared
/Pages/Shared
/Views/Shared

MVC

/Areas/<Area-Name>/Views/<Controller-Name>
/Areas/<Area-Name>/Views/Shared
/Views/Shared
/Pages/Shared

/Areas/<Area-Name>/Views/<Controller-Name>
/Areas/<Area-Name>/Views/Shared
/Views/Shared

다음 규칙이 부분 보기 검색에 적용됩니다.

부분 보기가 다른 폴더에 존재할 경우 파일 이름이 같은 다른 부분 보기가 허용됩니다.
파일 확장명 없이 이름으로 부분 보기를 참조하면서 부분 보기가 호출자의 폴더와 Shared 폴더 모두에 존재할 경우 호출자 폴더에 위치해 있는 부분 보기가 부분 보기를 제공합니다. 호출자의 폴더에 부분 보기가 존재하지 않으면 부분 보기는 Shared 폴더에서 제공됩니다. Shared 폴더의 부분 보기를 공유 부분 보기 또는 기본 부분 보기라고 합니다.
부분 보기를 연결할 수 있습니다. 부분 보기는 호출에 의해 순환 참조가 형성되지 않은 경우 다른 부분 보기를 호출할 수 있습니다. 상대 경로는 항상, 파일의 루트 또는 부모가 아닌 현재 파일에 상대적입니다.

참고 항목

Razorsection 부분 보기에 정의된 항목은 부모 태그 파일에 표시되지 않습니다. section은 정의되어 있는 부분 보기에만 표시됩니다.

부분 보기에서 데이터 액세스

부분 보기가 인스턴스화되면 부모의 ViewData 사전의 ‘사본’을 수신합니다. 부분 보기 내에서 데이터에 대한 업데이트는 부모 보기에 유지되지 않습니다. 부분 보기에서 변경된 ViewData는 부분 보기가 반환될 때 손실됩니다.

다음 예제에서는 부분 뷰에 인스턴스 ViewDataDictionary 를 전달하는 방법을 보여 줍니다.

@await Html.PartialAsync("_PartialName", customViewData)

모델을 부분 보기에 전달할 수 있습니다. 모델은 사용자 지정 개체일 수 있습니다. PartialAsync(콘텐츠 블록을 호출자에게 렌더링함) 또는 RenderPartialAsync(콘텐츠를 출력으로 스트리밍함)를 사용하여 모델을 전달할 수 있습니다.

@await Html.PartialAsync("_PartialName", model)

Razor Pages

샘플 앱의 다음 태그는 페이지에서 가져옵니다 Pages/ArticlesRP/ReadRP.cshtml . 페이지에는 두 개의 부분 보기가 있습니다. 두 번째 부분 보기는 모델 및 ViewData를 부분 보기에 전달합니다. ViewDataDictionary 생성자 오버로드를 사용하여 기존 ViewData 사전을 유지하면서 새로운 ViewData 사전을 전달합니다.

@model ReadRPModel

<h2>@Model.Article.Title</h2>
@* Pass the author's name to Pages\Shared\_AuthorPartialRP.cshtml *@
@await Html.PartialAsync("../Shared/_AuthorPartialRP", Model.Article.AuthorName)
@Model.Article.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Pages\ArticlesRP\_ArticleSectionRP.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Article.Sections)
    {
        await Html.PartialAsync("_ArticleSectionRP", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                });

        index++;
    }
}

Pages/Shared/_AuthorPartialRP.cshtml 는 태그 파일에서 참조하는 첫 번째 부분 보기입니다 ReadRP.cshtml .

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Pages/Shared/_AuthorPartialRP.cshtml.
</div>

Pages/ArticlesRP/_ArticleSectionRP.cshtml 는 태그 파일에서 참조하는 두 번째 부분 보기입니다 ReadRP.cshtml .

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

MVC

샘플 앱의 다음 태그는 보기를 보여 줍니다 Views/Articles/Read.cshtml . 보기에는 두 개의 부분 보기가 있습니다. 두 번째 부분 보기는 모델 및 ViewData를 부분 보기에 전달합니다. ViewDataDictionary 생성자 오버로드를 사용하여 기존 ViewData 사전을 유지하면서 새로운 ViewData 사전을 전달합니다.

@model PartialViewsSample.ViewModels.Article

<h2>@Model.Title</h2>
@* Pass the author's name to Views\Shared\_AuthorPartial.cshtml *@
@await Html.PartialAsync("_AuthorPartial", Model.AuthorName)
@Model.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Views\Articles\_ArticleSection.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Sections)
    {
        @(await Html.PartialAsync("_ArticleSection", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                }))

        index++;
    }
}

Views/Shared/_AuthorPartial.cshtml 는 태그 파일에서 참조하는 첫 번째 부분 보기입니다 Read.cshtml .

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Views/Shared/_AuthorPartial.cshtml.
</div>

Views/Articles/_ArticleSection.cshtml 는 태그 파일에서 참조하는 두 번째 부분 보기입니다 Read.cshtml .

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

런타임에 부분 요소는 부모 _Layout.cshtml태그 파일의 렌더링된 출력으로 렌더링되며, 이 출력은 공유된 파일 내에서 렌더링됩니다. 첫 번째 부분 보기는 문서 작성자의 이름과 게시 날짜를 렌더링합니다.

Abraham Lincoln

This partial view from <shared partial view file path>. 1863/11/19 12:00:00 AM

두 번째 부분 보기는 문서의 섹션을 렌더링합니다.

섹션 1 인덱스: 0

Four score and seven years ago ...

섹션 2 인덱스: 1

지금 멋진 전투에 참여하고 있습니다. 테스트 중...

섹션 3 인덱스: 2

But, in a larger sense, we can not dedicate ...

ASP.NET Core의 부분 보기

부분 보기를 사용하는 경우

부분 보기 선언

부분 보기 참조

Razor Pages PageModel에서 부분 보기 사용

태그 파일에서 부분 보기 사용

부분 태그 도우미

비동기 HTML 도우미

동기 HTML 도우미

부분 보기 검색

부분 보기에서 데이터 액세스

추가 리소스

피드백

추가 리소스