Teilansichten in ASP.NET Core

Von Steve Smith, Maher JENDOUBI, Rick Anderson und Scott Sauber

Eine Teilansicht ist eine Razor-Markupdatei (.cshtml) ohne @page-Direktive, die HTML-Ausgabe innerhalb der gerenderten Ausgabe einer anderen Markupdatei rendert.

Der Begriff Teilansicht wird verwendet, wenn entweder eine MVC-App entwickelt wird, in der Markupdateien Ansichten genannt werden, oder eine Razor Pages-App, in der Markupdateien Seiten genannt werden. In diesem Thema werden MVC-Ansichten und Razor Pages-Seiten allgemein als Markupdateien bezeichnet.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Wann werden Teilansichten verwendet?

Teilansichten bieten eine effektive Möglichkeit, um Folgendes zu erreichen:

• Aufteilen großer Markupdateien in kleinere Komponenten.

  In einer großen, komplexen Markupdatei, die aus mehreren logischen Teilen besteht, bringt es Vorteile mit sich, mit jeder einzelnen Komponente isoliert in einer Teilansicht zu arbeiten. Der Code in der Markupdatei ist verwaltbar, weil das Markup nur die allgemeine Seitenstruktur und Verweise auf Teilansichten enthält.

• Verringern der Duplizierung von allgemeinem Markupinhalt in Markupdateien.

  Wenn die gleichen Markupelemente in verschiedenen Markupdateien verwendet werden, entfernt eine Teilansicht die Duplizierung von Markupinhalten in einer Teilansichtsdatei. Wenn das Markup in der Teilansicht geändert wird, wird die gerenderte Ausgabe der Markupdateien aktualisiert, die die Teilansicht verwenden.

Teilansichten sollte nicht verwendet werden, um allgemeine Layoutelemente zu verwalten. Häufig verwendete Layoutelemente müssen in _Layout.cshtml-Dateien angegeben werden.

Verwenden Sie keine Teilansicht, wenn für das Rendern des Markups eine komplexe Renderinglogik oder Codeausführung erforderlich ist. Verwenden Sie anstelle einer Teilansicht eine Ansichtskomponente.

Deklarieren von Teilansichten

Eine Teilansicht ist eine .cshtml-Markupdatei ohne @page-Direktive, die innerhalb des Ordners Views (MVC) oder des Ordners Pages (Razor Pages) verwaltet wird.

In ASP.NET Core MVC kann ViewResult eines Controllers eine Ansicht oder eine Teilansicht zurückgeben. In Razor Pages kann ein PageModel eine Teilansicht zurückgeben, die als PartialViewResult-Objekt dargestellt wird. Das Verweisen auf und Rendern von Teilansichten wird im Abschnitt Verweisen auf eine Teilansicht beschrieben.

Im Gegensatz zum MVC-Ansichts- oder Seitenrendering führt eine Teilansicht _ViewStart.cshtml nicht aus. Weitere Informationen zu _ViewStart.cshtml finden Sie unter Layout in ASP.NET Core.

Dateinamen von Teilansichten beginnen häufig mit einem Unterstrich (_). Diese Namenskonvention ist keine Voraussetzung, sie hilft aber dabei, Teilansichten von Ansichten und Seiten visuell zu unterscheiden.

Verweisen auf eine Teilansicht

Verwenden einer Teilansicht in einem Razor Pages-PageModel

In ASP.NET Core 2.0 oder 2.1 rendert die folgende Handlermethode die Teilansicht _AuthorPartialRP.cshtml in der Antwort:

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

In ASP.NET Core 2.2 oder höher kann eine Handlermethode alternativ die Partial-Methode aufrufen, um ein PartialViewResult-Objekt zu erzeugen:

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

Verwenden einer Teilansicht in einer Markupdatei

Innerhalb einer Markupdatei gibt es mehrere Möglichkeiten, auf eine Teilansicht zu verweisen. Es wird empfohlen, dass Apps einen der folgenden Ansätze für asynchrones Rendering verwenden:

• Hilfsprogramm für Teiltags
• Asynchrones HTML-Hilfsprogramm

Hilfsprogramm für Teiltags

Das Hilfsprogramm für Teiltags erfordert ASP.NET Core 2.1 oder höher.

Das Hilfsprogramm für Teiltags rendert Inhalte asynchron und verwendet eine HTML-ähnliche Syntax:

<partial name="_PartialName" />

Wenn eine Dateierweiterung vorhanden ist, verweist das Hilfsprogramm für Teiltags auf eine Teilansicht, die sich im gleichen Ordner wie die Markupdatei befinden muss, die die Teilansicht aufruft:

<partial name="_PartialName.cshtml" />

Im folgende Beispiel wird aus dem Stammverzeichnis der App auf eine Teilansicht verwiesen. Pfade, die mit einer Tilde und einem Schrägstrich (~/) oder einem Schrägstrich (/) beginnen, verweisen auf den Stamm der App:

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" />

Das folgende Beispiel verweist auf eine Teilansicht mit einem relativen Pfad:

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

Weitere Informationen finden Sie unter Taghilfsprogramm für Teilansichten in ASP.NET Core.

Asynchrones HTML-Hilfsprogramm

Wenn Sie ein HTML-Hilfsprogramm verwenden, stellt das Verwenden von PartialAsync eine bewährte Methode dar. PartialAsync gibt einen IHtmlContent-Typ in einem Task<TResult> als Wrapper zurück. Sie können auf die Methode verweisen, indem Sie dem erwarteten Aufruf das Zeichen @ als Präfix voranstellen:

@await Html.PartialAsync("_PartialName")

Wenn die Dateierweiterung vorhanden ist, verweist das HTML-Hilfsprogramm auf eine Teilansicht, die sich im gleichen Ordner wie die Markupdatei befinden muss, die die Teilansicht aufruft:

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

Im folgende Beispiel wird aus dem Stammverzeichnis der App auf eine Teilansicht verwiesen. Pfade, die mit einer Tilde und einem Schrägstrich (~/) oder einem Schrägstrich (/) beginnen, verweisen auf den Stamm der App:

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")

Das folgende Beispiel verweist auf eine Teilansicht mit einem relativen Pfad:

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

Alternativ können Sie eine Teilansicht auch mit RenderPartialAsync rendern. Diese Methode gibt keinen IHtmlContent zurück. Sie streamt die gerenderte Ausgabe direkt an die Antwort. Da die Methode kein Ergebnis zurückgibt, muss sie in einem Razor-Codeblock aufgerufen werden:

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

Da RenderPartialAsync gerenderte Inhalte streamt, bietet diese Vorgehensweise in einigen Szenarien eine bessere Leistung. In leistungskritischen Situationen sollten Sie die Seite mit beiden Ansätzen einem Benchmarktest unterziehen und den Ansatz verwenden, der eine schnellere Antwort generiert.

Synchrones HTML-Hilfsprogramm

Partial und RenderPartial sind die synchronen Entsprechungen von PartialAsync bzw. RenderPartialAsync. Diese synchronen Entsprechungen werden nicht empfohlen, da sie in manchen Szenarien zu einem Deadlock führen können. Die synchronen Methoden sollen in einem zukünftigen Release entfernt werden.

Wichtig

Wenn Sie Code ausführen müssen, verwenden Sie anstelle von Teilansichten Ansichtskomponenten.

Das Aufrufen von Partial oder RenderPartial führt zu einer Visual Studio Analyzer-Warnung. Beispielsweise führt das Vorhandensein von Partial zu folgender Warnmeldung:

Die Verwendung von IHtmlHelper.Partial kann zu Anwendungsdeadlocks führen. Erwägen Sie die Verwendung des Hilfsprogramms für <Teiltags> oder von IHtmlHelper.PartialAsync.

Ersetzen Sie Aufrufe von @Html.Partial durch @await Html.PartialAsync oder durch das Hilfsprogramm für Teiltags. Weiter Informationen zur Migration des Teiltaghilfsprogramms finden Sie unter Migrate from an HTML Helper (Migration von einem HTML-Hilfsprogramm)

Ermittlung von Teilansichten

Wenn auf eine Teilansicht anhand des Namens ohne eine Dateierweiterung verwiesen wird, werden die folgenden Speicherorte in der angegebenen Reihenfolge durchsucht:

Razor Pages

1. Der Ordner der aktuell ausgeführten Seite
2. Der Verzeichnisgraph über dem Ordner der Seite
3. /Shared
4. /Pages/Shared
5. /Views/Shared

MVC

1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
4. /Pages/Shared

Für die Ermittlung von Teilansichten gelten die folgenden Konventionen:

• Unterschiedliche Teilansichten mit dem gleichen Dateinamen sind zulässig, wenn sich die Teilansichten in verschiedenen Ordnern befinden.
• Wenn auf eine Teilansicht über den Namen ohne Dateierweiterung verwiesen wird und die Teilansicht sowohl im Ordner des Aufrufers als auch im Ordner Shared vorhanden ist, stellt die Teilansicht im Ordner des Aufrufers die Teilansicht bereit. Wenn die Teilansicht nicht im Ordner des Aufrufers vorhanden ist, wird die Teilansicht aus dem Ordner Shared bereitgestellt. Teilansichten im Ordner Shared werden als Freigegebene Teilansichten oder Standardteilansichten bezeichnet.
• Teilansichten können verkettet werden: Eine Teilansicht kann eine andere Teilansicht aufrufen, wenn durch den Aufruf kein Zirkelbezug entsteht. Relative Pfade sind immer relativ zur aktuellen Datei, nicht zum Stamm- oder übergeordneten Verzeichnis der Datei.

Hinweis

Ein in einer Teilansicht definierter Razor section ist für übergeordnete Markupdateien nicht sichtbar. Die section-Anweisung ist nur für die Teilansicht, in der sie definiert ist, sichtbar.

Zugriff auf Daten aus Teilansichten

Wenn eine Teilansicht instanziiert wird, erhält sie eine Kopie des ViewData-Wörterbuchs der übergeordneten Ansicht. An den Daten vorgenommene Änderungen in der Teilansicht werden in der übergeordneten Ansicht nicht beibehalten. Ein ViewData-Wörterbuch, das in einer Teilansicht verändert wird, geht verloren, wenn die Teilansicht eine Rückgabe ausgibt.

Das folgende Beispiel zeigt, wie eine Instanz von ViewDataDictionary an eine Teilansicht übergeben wird:

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

Außerdem können Sie ein Modell an eine Teilansicht übergeben. Das Modell kann ein benutzerdefiniertes Objekt sein. Sie können ein Modell mit PartialAsync (rendert einen Inhaltsblock für den Aufrufer) oder RenderPartialAsync (streamt den Inhalt in die Ausgabe) übergeben:

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

Razor Pages

Das folgende Markup in der Beispiel-App stammt aus der Seite Pages/ArticlesRP/ReadRP.cshtml. Diese Seite enthält zwei Teilansichten. Die zweite Teilansicht übergibt ein Modell und ViewData an die Teilansicht. Die ViewDataDictionary-Konstruktorüberladung wird verwendet, um ein neues ViewData-Wörterbuch zu übergeben, während das vorhandene ViewData-Wörterbuch beibehalten wird.

@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 ist die erste Teilansicht, auf die in der ReadRP.cshtml-Markupdatei verwiesen wird:

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml ist die zweite Teilansicht, auf die in der ReadRP.cshtml-Markupdatei verwiesen wird:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC

Das folgende Markup in der Beispiel-App zeigt die Views/Articles/Read.cshtml-Ansicht. Die Ansicht enthält die zwei Teilansichten. Die zweite Teilansicht übergibt ein Modell und ViewData an die Teilansicht. Die ViewDataDictionary-Konstruktorüberladung wird verwendet, um ein neues ViewData-Wörterbuch zu übergeben, während das vorhandene ViewData-Wörterbuch beibehalten wird.

@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 ist die erste Teilansicht, auf die in der Read.cshtml-Markupdatei verwiesen wird:

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

Views/Articles/_ArticleSection.cshtml ist die zweite Teilansicht, auf die in der Read.cshtml-Markupdatei verwiesen wird:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Die Teilansichten werden zur Laufzeit in der gerenderten Ausgabe der übergeordneten Markupdatei gerendert, die wiederum in der freigegebenen Datei _Layout.cshtml gerendert wird. Die erste Teilansicht rendert den Namen des Artikelautors und das Erscheinungsdatum:

Abraham Lincoln

Diese Teilansicht aus dem <Dateipfad der freigegebenen Teilansicht>. 11/19/1863 12:00:00 AM

Die zweite Teilansicht rendert die Abschnitte des Artikels:

Section One Index: 0

Four score and seven years ago ...

Section Two Index: 1

Now we are engaged in a great civil war, testing ...

Section Three Index: 2

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

Zusätzliche Ressourcen

• Razor-Syntaxreferenz für ASP.NET Core
• Taghilfsprogramme in ASP.NET Core
• Hilfsprogramm für Teiltags in ASP.NET Core
• Ansichtskomponenten in ASP.NET Core
• Bereiche in ASP.NET Core