Verwenden von Teilansichten in ASP.NET CorePartial views in ASP.NET Core

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

Eine Teilansicht ist eine Razor Markup Datei (. cshtml) ohne eine- @page Direktive, die die HTML-Ausgabe innerhalb der gerenderten Ausgabe einer anderen Markup Datei rendert.A partial view is a Razor markup file (.cshtml) without an @page directive that renders HTML output within another markup file's rendered output.

Der Begriff " Teilansicht " wird verwendet, wenn eine MVC-app entwickelt wird, in der Markup Dateien als Sichten bezeichnet werden, oder eine Razor pages-APP, bei der Markup Dateien als Seiten bezeichnet werden.The term partial view is used when developing either an MVC app, where markup files are called views, or a Razor Pages app, where markup files are called pages. Dieses Thema verweist generisch auf MVC-Ansichten und Razor Seiten Seiten als Markup Dateien.This topic generically refers to MVC views and Razor Pages pages as markup files.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)View or download sample code (how to download)

Wann werden Teilansichten verwendet?When to use partial views

Teilansichten bieten eine effektive Möglichkeit, um Folgendes zu erreichen:Partial views are an effective way to:

  • Aufteilen großer Markupdateien in kleinere Komponenten.Break up large markup files into smaller components.

    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.In a large, complex markup file composed of several logical pieces, there's an advantage to working with each piece isolated into a partial view. Der Code in der Markupdatei ist verwaltbar, weil das Markup nur die allgemeine Seitenstruktur und Verweise auf Teilansichten enthält.The code in the markup file is manageable because the markup only contains the overall page structure and references to partial views.

  • Verringern der Duplizierung von allgemeinem Markupinhalt in Markupdateien.Reduce the duplication of common markup content across markup files.

    Wenn die gleichen Markupelemente in verschiedenen Markupdateien verwendet werden, entfernt eine Teilansicht die Duplizierung von Markupinhalten in einer Teilansichtsdatei.When the same markup elements are used across markup files, a partial view removes the duplication of markup content into one partial view file. Wenn das Markup in der Teilansicht geändert wird, wird die gerenderte Ausgabe der Markupdateien aktualisiert, die die Teilansicht verwenden.When the markup is changed in the partial view, it updates the rendered output of the markup files that use the partial view.

Teilansichten sollte nicht verwendet werden, um allgemeine Layoutelemente zu verwalten.Partial views shouldn't be used to maintain common layout elements. Häufig verwendete Layoutelemente müssen in _Layout.cshtml-Dateien angegeben werden.Common layout elements should be specified in _Layout.cshtml files.

Verwenden Sie keine Teilansicht, wenn für das Rendern des Markups eine komplexe Renderinglogik oder Codeausführung erforderlich ist.Don't use a partial view where complex rendering logic or code execution is required to render the markup. Verwenden Sie anstelle einer Teilansicht eine Ansichtskomponente.Instead of a partial view, use a view component.

Deklarieren von TeilansichtenDeclare partial views

Eine Teilansicht ist eine cshtml -Markup Datei ohne eine- @page Direktive, die im Ordner views (MVC) oder im Ordner pages ( Razor Seiten) beibehalten wird.A partial view is a .cshtml markup file without an @page directive maintained within the Views folder (MVC) or Pages folder (Razor Pages).

In ASP.NET Core MVC kann ViewResult eines Controllers eine Ansicht oder eine Teilansicht zurückgeben.In ASP.NET Core MVC, a controller's ViewResult is capable of returning either a view or a partial view. In Razor Seiten kann eine PageModel eine partielle Ansicht zurückgeben, die als-Objekt dargestellt wird PartialViewResult .In Razor Pages, a PageModel can return a partial view represented as a PartialViewResult object. Das Verweisen auf und Rendern von Teilansichten wird im Abschnitt Verweisen auf eine Teilansicht beschrieben.Referencing and rendering partial views is described in the Reference a partial view section.

Im Gegensatz zu MVC-Ansichten oder Seitenrendering führt eine Teilansicht _ViewStart.cshtml nicht aus.Unlike MVC view or page rendering, a partial view doesn't run _ViewStart.cshtml. Weitere Informationen zu _ViewStart.cshtml finden Sie unter Layout in ASP.NET Core.For more information on _ViewStart.cshtml, see Layout in ASP.NET Core.

Dateinamen von Teilansichten beginnen häufig mit einem Unterstrich (_).Partial view file names often begin with an underscore (_). Diese Namenskonvention ist keine Voraussetzung, sie hilft aber dabei, Teilansichten von Ansichten und Seiten visuell zu unterscheiden.This naming convention isn't required, but it helps to visually differentiate partial views from views and pages.

Eine Teilansicht ist eine CSHTML-Markupdatei, die innerhalb des Ordners Views verwaltet wird.A partial view is a .cshtml markup file maintained within the Views folder.

ViewResult eines Controllers kann eine Ansicht oder eine Teilansicht zurückgeben.A controller's ViewResult is capable of returning either a view or a partial view. Das Verweisen auf und Rendern von Teilansichten wird im Abschnitt Verweisen auf eine Teilansicht beschrieben.Referencing and rendering partial views is described in the Reference a partial view section.

Im Gegensatz zu MVC-Ansichten oder Rendering führt eine Teilansicht _ViewStart.cshtml nicht aus.Unlike MVC view rendering, a partial view doesn't run _ViewStart.cshtml. Weitere Informationen zu _ViewStart.cshtml finden Sie unter Layout in ASP.NET Core.For more information on _ViewStart.cshtml, see Layout in ASP.NET Core.

Dateinamen von Teilansichten beginnen häufig mit einem Unterstrich (_).Partial view file names often begin with an underscore (_). Diese Namenskonvention ist keine Voraussetzung, sie hilft aber dabei, Teilansichten von Ansichten visuell zu unterscheiden.This naming convention isn't required, but it helps to visually differentiate partial views from views.

Verweisen auf eine TeilansichtReference a partial view

Verwenden einer Teilansicht in Razor Seiten Modellen für SeitenUse a partial view in a Razor Pages PageModel

In ASP.net Core 2,0 oder 2,1 rendert die folgende Handlermethode die Teilansicht _ authorpartialrp. cshtml für die Antwort:In ASP.NET Core 2.0 or 2.1, the following handler method renders the _AuthorPartialRP.cshtml partial view to the response:

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:In ASP.NET Core 2.2 or later, a handler method can alternatively call the Partial method to produce a PartialViewResult object:

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

Verwenden einer Teilansicht in einer MarkupdateiUse a partial view in a markup file

Innerhalb einer Markupdatei gibt es mehrere Möglichkeiten, auf eine Teilansicht zu verweisen.Within a markup file, there are several ways to reference a partial view. Es wird empfohlen, dass Apps einen der folgenden Ansätze für asynchrones Rendering verwenden:We recommend that apps use one of the following asynchronous rendering approaches:

Innerhalb einer Markupdatei gibt es zwei Möglichkeiten, auf eine Teilansicht zu verweisen:Within a markup file, there are two ways to reference a partial view:

Es wird empfohlen, dass Apps das asynchrone HTML-Hilfsprogramm verwenden.We recommend that apps use the Asynchronous HTML Helper.

Hilfsprogramm für TeiltagsPartial Tag Helper

Das Hilfsprogramm für Teiltags erfordert ASP.NET Core 2.1 oder höher.The Partial Tag Helper requires ASP.NET Core 2.1 or later.

Das Hilfsprogramm für Teiltags rendert Inhalte asynchron und verwendet eine HTML-ähnliche Syntax:The Partial Tag Helper renders content asynchronously and uses an HTML-like 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:When a file extension is present, the Tag Helper references a partial view that must be in the same folder as the markup file calling the partial view:

<partial name="_PartialName.cshtml" />

Im folgende Beispiel wird aus dem Stammverzeichnis der App auf eine Teilansicht verwiesen.The following example references a partial view from the app root. Pfade, die mit einer Tilde und einem Schrägstrich (~/) oder einem Schrägstrich (/) beginnen, verweisen auf den Stamm der App:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Razor SeitenRazor Pages

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

MVCMVC

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

Das folgende Beispiel verweist auf eine Teilansicht mit einem relativen Pfad:The following example references a partial view with a relative path:

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

Weitere Informationen finden Sie unter Hilfsprogramm für Teiltags in ASP.NET Core.For more information, see Hilfsprogramm für Teiltags in ASP.NET Core.

Hilfsprogramm für asynchrone HTMLAsynchronous HTML Helper

Wenn Sie ein HTML-Hilfsprogramm verwenden, stellt das Verwenden von PartialAsync eine bewährte Methode dar.When using an HTML Helper, the best practice is to use PartialAsync. PartialAsync gibt einen IHtmlContent-Typ in einem Task<TResult> als Wrapper zurück.PartialAsync returns an IHtmlContent type wrapped in a Task<TResult>. Sie können auf die Methode verweisen, indem Sie dem erwarteten Aufruf das Zeichen @ als Präfix voranstellen:The method is referenced by prefixing the awaited call with an @ character:

@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:When the file extension is present, the HTML Helper references a partial view that must be in the same folder as the markup file calling the partial view:

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

Im folgende Beispiel wird aus dem Stammverzeichnis der App auf eine Teilansicht verwiesen.The following example references a partial view from the app root. Pfade, die mit einer Tilde und einem Schrägstrich (~/) oder einem Schrägstrich (/) beginnen, verweisen auf den Stamm der App:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Razor SeitenRazor Pages

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

MVCMVC

@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:The following example references a partial view with a relative path:

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

Alternativ können Sie eine Teilansicht auch mit RenderPartialAsync rendern.Alternatively, you can render a partial view with RenderPartialAsync. Diese Methode gibt keinen IHtmlContent zurück.This method doesn't return an IHtmlContent. Sie streamt die gerenderte Ausgabe direkt an die Antwort.It streams the rendered output directly to the response. Da die Methode kein Ergebnis zurückgibt, muss Sie in einem Razor Codeblock aufgerufen werden:Because the method doesn't return a result, it must be called within a Razor code block:

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

Da RenderPartialAsync gerenderte Inhalte streamt, bietet diese Vorgehensweise in einigen Szenarien eine bessere Leistung.Since RenderPartialAsync streams rendered content, it provides better performance in some scenarios. In leistungskritischen Situationen sollten Sie die Seite mit beiden Ansätzen einem Benchmarktest unterziehen und den Ansatz verwenden, der eine schnellere Antwort generiert.In performance-critical situations, benchmark the page using both approaches and use the approach that generates a faster response.

Hilfsprogramm für synchrone HTMLSynchronous HTML Helper

Partial und RenderPartial sind die synchronen Entsprechungen von PartialAsync bzw. RenderPartialAsync.Partial and RenderPartial are the synchronous equivalents of PartialAsync and RenderPartialAsync, respectively. Diese synchronen Entsprechungen werden nicht empfohlen, da sie in manchen Szenarien zu einem Deadlock führen können.The synchronous equivalents aren't recommended because there are scenarios in which they deadlock. Die synchronen Methoden sollen in einem zukünftigen Release entfernt werden.The synchronous methods are targeted for removal in a future release.

Wichtig

Wenn Sie Code ausführen müssen, verwenden Sie anstelle von Teilansichten Ansichtskomponenten.If you need to execute code, use a view component instead of a partial view.

Das Aufrufen von Partial oder RenderPartial führt zu einer Visual Studio Analyzer-Warnung.Calling Partial or RenderPartial results in a Visual Studio analyzer warning. Beispielsweise führt das Vorhandensein von Partial zu folgender Warnmeldung:For example, the presence of Partial yields the following warning message:

Die Verwendung von IHtmlHelper.Partial kann zu Anwendungsdeadlocks führen.Use of IHtmlHelper.Partial may result in application deadlocks. Erwägen Sie die Verwendung des Hilfsprogramms für <Teiltags> oder von IHtmlHelper.PartialAsync.Consider using <partial> Tag Helper or IHtmlHelper.PartialAsync.

Ersetzen Sie Aufrufe von @Html.Partial durch @await Html.PartialAsync oder durch das Hilfsprogramm für Teiltags.Replace calls to @Html.Partial with @await Html.PartialAsync or the Partial Tag Helper. Weiter Informationen zur Migration des Teiltaghilfsprogramms finden Sie unter Migrate from an HTML Helper (Migration von einem HTML-Hilfsprogramm)For more information on Partial Tag Helper migration, see Migrate from an HTML Helper.

Ermittlung von TeilansichtenPartial view discovery

Wenn auf eine Teilansicht anhand des Namens ohne eine Dateierweiterung verwiesen wird, werden die folgenden Speicherorte in der angegebenen Reihenfolge durchsucht:When a partial view is referenced by name without a file extension, the following locations are searched in the stated order:

Razor SeitenRazor Pages

  1. Der Ordner der aktuell ausgeführten SeiteCurrently executing page's folder
  2. Der Verzeichnisgraph über dem Ordner der SeiteDirectory graph above the page's folder
  3. /Shared
  4. /Pages/Shared
  5. /Views/Shared

MVCMVC

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

Für die Ermittlung von Teilansichten gelten die folgenden Konventionen:The following conventions apply to partial view discovery:

  • Unterschiedliche Teilansichten mit dem gleichen Dateinamen sind zulässig, wenn sich die Teilansichten in verschiedenen Ordnern befinden.Different partial views with the same file name are allowed when the partial views are in different folders.
  • 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.When referencing a partial view by name without a file extension and the partial view is present in both the caller's folder and the Shared folder, the partial view in the caller's folder supplies the partial view. Wenn die Teilansicht nicht im Ordner des Aufrufers vorhanden ist, wird die Teilansicht aus dem Ordner Shared bereitgestellt.If the partial view isn't present in the caller's folder, the partial view is provided from the Shared folder. Teilansichten im Ordner Shared werden als Freigegebene Teilansichten oder Standardteilansichten bezeichnet.Partial views in the Shared folder are called shared partial views or default partial views.
  • Teilansichten können verkettet werden — . eine partielle Ansicht kann eine andere partielle Sicht aufrufen, wenn ein Zirkel Verweis nicht durch die Aufrufe gebildet wird.Partial views can be chained—a partial view can call another partial view if a circular reference isn't formed by the calls. Relative Pfade sind immer relativ zur aktuellen Datei, nicht zum Stamm- oder übergeordneten Verzeichnis der Datei.Relative paths are always relative to the current file, not to the root or parent of the file.

Hinweis

Ein Razor section , der in einer Teilansicht definiert ist, ist für übergeordnete Markup Dateien nicht sichtbar.A Razor section defined in a partial view is invisible to parent markup files. Die section-Anweisung ist nur für die Teilansicht, in der sie definiert ist, sichtbar.The section is only visible to the partial view in which it's defined.

Zugriff auf Daten aus TeilansichtenAccess data from partial views

Wenn eine Teilansicht instanziiert wird, erhält sie eine Kopie des ViewData-Wörterbuchs der übergeordneten Ansicht.When a partial view is instantiated, it receives a copy of the parent's ViewData dictionary. An den Daten vorgenommene Änderungen in der Teilansicht werden in der übergeordneten Ansicht nicht beibehalten.Updates made to the data within the partial view aren't persisted to the parent view. Ein ViewData-Wörterbuch, das in einer Teilansicht verändert wird, geht verloren, wenn die Teilansicht eine Rückgabe ausgibt.ViewData changes in a partial view are lost when the partial view returns.

Das folgende Beispiel zeigt, wie eine Instanz von ViewDataDictionary an eine Teilansicht übergeben wird:The following example demonstrates how to pass an instance of ViewDataDictionary to a partial view:

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

Außerdem können Sie ein Modell an eine Teilansicht übergeben.You can pass a model into a partial view. Das Modell kann ein benutzerdefiniertes Objekt sein.The model can be a custom object. Sie können ein Modell mit PartialAsync (rendert einen Inhaltsblock für den Aufrufer) oder RenderPartialAsync (streamt den Inhalt in die Ausgabe) übergeben:You can pass a model with PartialAsync (renders a block of content to the caller) or RenderPartialAsync (streams the content to the output):

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

Razor SeitenRazor Pages

Das folgende Markup in der Beispiel-App stammt von der Seite Pages/ArticlesRP/ReadRP.cshtml.The following markup in the sample app is from the Pages/ArticlesRP/ReadRP.cshtml page. Diese Seite enthält zwei Teilansichten.The page contains two partial views. Die zweite Teilansicht übergibt ein Modell und ViewData an die Teilansicht.The second partial view passes in a model and ViewData to the partial view. Die ViewDataDictionary-Konstruktorüberladung wird verwendet, um ein neues ViewData-Wörterbuch zu übergeben, während das vorhandene ViewData-Wörterbuch beibehalten wird.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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 durch die Markupdatei ReadRP.cshtml verwiesen wird:Pages/Shared/_AuthorPartialRP.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:

@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 durch die Markupdatei ReadRP.cshtml verwiesen wird:Pages/ArticlesRP/_ArticleSectionRP.cshtml is the second partial view referenced by the ReadRP.cshtml markup file:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVCMVC

Das folgende Markup in der Beispiel-App zeigt die Ansicht Views/Articles/Read.cshtml.The following markup in the sample app shows the Views/Articles/Read.cshtml view. Die Ansicht enthält die zwei Teilansichten.The view contains two partial views. Die zweite Teilansicht übergibt ein Modell und ViewData an die Teilansicht.The second partial view passes in a model and ViewData to the partial view. Die ViewDataDictionary-Konstruktorüberladung wird verwendet, um ein neues ViewData-Wörterbuch zu übergeben, während das vorhandene ViewData-Wörterbuch beibehalten wird.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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 durch die Markupdatei Read.cshtml verwiesen wird:Views/Shared/_AuthorPartial.cshtml is the first partial view referenced by the Read.cshtml markup file:

@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 durch die Markupdatei ReadRP.cshtml verwiesen wird:Views/Articles/_ArticleSection.cshtml is the second partial view referenced by the Read.cshtml markup file:

@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.At runtime, the partials are rendered into the parent markup file's rendered output, which itself is rendered within the shared _Layout.cshtml. Die erste Teilansicht rendert den Namen des Artikelautors und das Erscheinungsdatum:The first partial view renders the article author's name and publication date:

Abraham LincolnAbraham Lincoln

Diese Teilansicht aus dem <Dateipfad der freigegebenen Teilansicht>.This partial view from <shared partial view file path>. 11/19/1863 12:00:00 AM11/19/1863 12:00:00 AM

Die zweite Teilansicht rendert die Abschnitte des Artikels:The second partial view renders the article's sections:

Section One Index: 0Section One Index: 0

Four score and seven years ago ...Four score and seven years ago ...

Section Two Index: 1Section Two Index: 1

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

Section Three Index: 2Section Three Index: 2

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

Zusätzliche RessourcenAdditional resources