Visualizzazioni parziali in ASP.NET CorePartial views in ASP.NET Core

Di Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson e Scott SauberBy Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson, and Scott Sauber

Una visualizzazione parziale è un file di markup Razor (con estensione cshtml) che esegue il rendering dell'output HTML all'interno dell'output sottoposto a rendering di un altro file di markup.A partial view is a Razor markup file (.cshtml) that renders HTML output within another markup file's rendered output.

Il termine visualizzazione parziale viene usato nell'ambito dello sviluppo di app MVC, in cui i file di markup si chiamano visualizzazioni, o di app Razor Pages, dove i file di markup si chiamano pagine.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. Questo argomento si riferisce genericamente alle visualizzazioni MVC e alle pagine Razor Pages come file di markup.This topic generically refers to MVC views and Razor Pages pages as markup files.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Quando usare le visualizzazioni parzialiWhen to use partial views

Le visualizzazioni parziali sono un modo efficace di:Partial views are an effective way to:

  • Suddividere file di markup di grandi dimensioni in componenti più piccoli.Break up large markup files into smaller components.

    In un file di markup complesso e di grandi dimensioni, composto da diverse parti logiche, gestire ognuna di queste parti isolate in una visualizzazione parziale offre dei vantaggi.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. Il codice del file di markup è infatti gestibile in quanto il markup contiene solo la struttura della pagina complessiva e riferimenti alle visualizzazioni parziali.The code in the markup file is manageable because the markup only contains the overall page structure and references to partial views.

  • Ridurre la duplicazione del contenuto di markup comune nei file di markup.Reduce the duplication of common markup content across markup files.

    Quando nei vari file di markup vengono usati gli stessi elementi di markup, una visualizzazione parziale rimuove la duplicazione del contenuto di markup in un file di visualizzazione parziale.When the same markup elements are used across markup files, a partial view removes the duplication of markup content into one partial view file. Quando il markup viene modificato nella visualizzazione parziale, aggiorna l'output sottoposto a rendering dei file di markup che usano la visualizzazione parziale.When the markup is changed in the partial view, it updates the rendered output of the markup files that use the partial view.

Le visualizzazioni parziali non devono essere usate per gestire gli elementi di layout comuni.Partial views shouldn't be used to maintain common layout elements. Gli elementi comuni del layout devono essere specificati nei file _Layout.cshtml.Common layout elements should be specified in _Layout.cshtml files.

Non usare una visualizzazione parziale in cui per il rendering del markup è necessaria una logica di rendering complessa o l'esecuzione di codice.Don't use a partial view where complex rendering logic or code execution is required to render the markup. Invece di una visualizzazione parziale, usare un componente di visualizzazione.Instead of a partial view, use a view component.

Dichiarare le visualizzazioni parzialiDeclare partial views

Una visualizzazione parziale è un file di markup con estensione cshtml che si trova nella cartella Views (MVC) o Pages (Razor Pages).A partial view is a .cshtml markup file maintained within the Views folder (MVC) or Pages folder (Razor Pages).

In ASP.NET Core MVC, l'elemento ViewResult di un controller è in grado di restituire una visualizzazione o una visualizzazione parziale.In ASP.NET Core MVC, a controller's ViewResult is capable of returning either a view or a partial view. In Razor Pages un PageModel può restituire una visualizzazione parziale rappresentata come oggetto PartialViewResult.In Razor Pages, a PageModel can return a partial view represented as a PartialViewResult object. Il riferimento e il rendering delle visualizzazioni parziali sono descritti nella sezione Riferimento a una visualizzazione parziale.Referencing and rendering partial views is described in the Reference a partial view section.

A differenza del rendering di pagine o visualizzazioni MVC, una visualizzazione parziale non esegue _ViewStart.cshtml.Unlike MVC view or page rendering, a partial view doesn't run _ViewStart.cshtml. Per altre informazioni su _ViewStart.cshtml, vedere Layout in ASP.NET Core.For more information on _ViewStart.cshtml, see Layout in ASP.NET Core.

I nomi dei file di visualizzazione parziale iniziano spesso con un carattere di sottolineatura (_).Partial view file names often begin with an underscore (_). Questa convenzione di denominazione non è obbligatoria, ma è utile per differenziare visivamente le visualizzazioni parziali dalle visualizzazioni e dalle pagine.This naming convention isn't required, but it helps to visually differentiate partial views from views and pages.

Una visualizzazione parziale è un file di markup con estensione cshtml che si trova nella cartella Views.A partial view is a .cshtml markup file maintained within the Views folder.

L'elemento ViewResult di un controller è in grado di restituire una visualizzazione o una visualizzazione parziale.A controller's ViewResult is capable of returning either a view or a partial view. Il riferimento e il rendering delle visualizzazioni parziali sono descritti nella sezione Riferimento a una visualizzazione parziale.Referencing and rendering partial views is described in the Reference a partial view section.

A differenza del rendering di visualizzazioni MVC, una visualizzazione parziale non esegue _ViewStart.cshtml.Unlike MVC view rendering, a partial view doesn't run _ViewStart.cshtml. Per altre informazioni su _ViewStart.cshtml, vedere Layout in ASP.NET Core.For more information on _ViewStart.cshtml, see Layout in ASP.NET Core.

I nomi dei file di visualizzazione parziale iniziano spesso con un carattere di sottolineatura (_).Partial view file names often begin with an underscore (_). Questa convenzione di denominazione non è obbligatoria, ma è utile per differenziare visivamente le visualizzazioni parziali dalle visualizzazioni.This naming convention isn't required, but it helps to visually differentiate partial views from views.

Riferimento a una visualizzazione parzialeReference a partial view

Usare una visualizzazione parziale in un PageModel di Razor PagesUse a partial view in a Razor Pages PageModel

In ASP.NET Core 2.0 o 2.1, il metodo del gestore seguente esegue il rendering della visualizzazione parziale _AuthorPartialRP.cshtml nella risposta: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 o versioni successive, un metodo del gestore può chiamare in alternativa il metodo Partial per produrre un oggetto PartialViewResult: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");

Usare una visualizzazione parziale in un file di markupUse a partial view in a markup file

All'interno di un file di markup è possibile fare riferimento a una visualizzazione parziale in diversi modi.Within a markup file, there are several ways to reference a partial view. È consigliabile usare uno dei metodi asincroni seguenti nelle app:We recommend that apps use one of the following asynchronous rendering approaches:

All'interno di un file di markup è possibile fare riferimento a una visualizzazione parziale in due modi:Within a markup file, there are two ways to reference a partial view:

È consigliabile usare l'helper HTML asincrono nelle app.We recommend that apps use the Asynchronous HTML Helper.

Helper tag PartialPartial Tag Helper

L'helper tag Partial richiede ASP.NET Core 2.1 o versioni successive.The Partial Tag Helper requires ASP.NET Core 2.1 or later.

Questo helper esegue il rendering del contenuto in modo asincrono e usa una sintassi HTML:The Partial Tag Helper renders content asynchronously and uses an HTML-like syntax:

<partial name="_PartialName" />

Quando è presente un'estensione di file, l'helper tag fa riferimento a una visualizzazione parziale che deve essere contenuta nella stessa cartella in cui si trova il file di markup che chiama la visualizzazione parziale: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" />

L'esempio seguente fa riferimento a una visualizzazione parziale dalla radice dell'app.The following example references a partial view from the app root. I percorsi che iniziano con una tilde e una barra (~/) o con una barra (/) fanno riferimento alla radice dell'app:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

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

L'esempio seguente fa riferimento a una visualizzazione parziale con un percorso relativo:The following example references a partial view with a relative path:

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

Per altre informazioni, vedere Helper tag Partial in ASP.NET Core.For more information, see Helper tag Partial in ASP.NET Core.

Helper HTML asincronoAsynchronous HTML Helper

Quando si usa un helper HTML, la procedura consigliata consiste nell'usare PartialAsync.When using an HTML Helper, the best practice is to use PartialAsync. PartialAsync restituisce un tipo IHtmlContent di cui è stato eseguito il wrapping in un Task<TResult>.PartialAsync returns an IHtmlContent type wrapped in a Task<TResult>. Il riferimento al metodo avviene facendo precedere la chiamata attesa da un carattere @:The method is referenced by prefixing the awaited call with an @ character:

@await Html.PartialAsync("_PartialName")

Quando è presente l'estensione di file, l'helper HTML fa riferimento a una visualizzazione parziale che deve essere contenuta nella stessa cartella in cui si trova il file di markup che chiama la visualizzazione parziale: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")

L'esempio seguente fa riferimento a una visualizzazione parziale dalla radice dell'app.The following example references a partial view from the app root. I percorsi che iniziano con una tilde e una barra (~/) o con una barra (/) fanno riferimento alla radice dell'app:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

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

L'esempio seguente fa riferimento a una visualizzazione parziale con un percorso relativo:The following example references a partial view with a relative path:

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

In alternativa è possibile eseguire il rendering di una visualizzazione parziale con RenderPartialAsync.Alternatively, you can render a partial view with RenderPartialAsync. Questo metodo non restituisce un IHtmlContent.This method doesn't return an IHtmlContent. Trasmette l'output sottoposto a rendering direttamente alla risposta.It streams the rendered output directly to the response. Poiché il metodo non restituisce un risultato, deve essere chiamato all'interno di un blocco di codice Razor:Because the method doesn't return a result, it must be called within a Razor code block:

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

Poiché RenderPartialAsync trasmette il contenuto sottoposto a rendering, assicura prestazioni migliori in alcuni scenari.Since RenderPartialAsync streams rendered content, it provides better performance in some scenarios. In situazioni in cui le prestazioni sono importanti, eseguire il benchmark della pagina usando entrambi gli approcci e usare quindi l'approccio che genera una risposta più rapidamente.In performance-critical situations, benchmark the page using both approaches and use the approach that generates a faster response.

Helper HTML sincronoSynchronous HTML Helper

Partial e RenderPartial sono gli equivalenti sincroni rispettivamente di PartialAsync e RenderPartialAsync.Partial and RenderPartial are the synchronous equivalents of PartialAsync and RenderPartialAsync, respectively. L'uso degli equivalenti sincroni non è consigliabile perché in alcuni scenari causano un deadlock.The synchronous equivalents aren't recommended because there are scenarios in which they deadlock. I metodi sincroni verranno rimossi in una versione futura.The synchronous methods are targeted for removal in a future release.

Importante

Se è necessario eseguire codice, usare un componente di visualizzazione invece di una visualizzazione parziale.If you need to execute code, use a view component instead of a partial view.

La chiamata di Partial o RenderPartial genera un avviso di Visual Studio Analyzer.Calling Partial or RenderPartial results in a Visual Studio analyzer warning. Ad esempio, la presenza di Partial produce il messaggio di avviso seguente:For example, the presence of Partial yields the following warning message:

L'uso di IHtmlHelper.Partial potrebbe determinare deadlock dell'applicazione.Use of IHtmlHelper.Partial may result in application deadlocks. È consigliabile usare l'helper tag <Partial> o IHtmlHelper.PartialAsync.Consider using <partial> Tag Helper or IHtmlHelper.PartialAsync.

Sostituire le chiamate a @Html.Partial con @await Html.PartialAsync o con l'helper tag Partial.Replace calls to @Html.Partial with @await Html.PartialAsync or the Partial Tag Helper. Per altre informazioni sulla migrazione dell'helper tag Partial, vedere Eseguire la migrazione da un helper HTML.For more information on Partial Tag Helper migration, see Migrate from an HTML Helper.

Individuazione delle visualizzazioni parzialiPartial view discovery

Quando si fa riferimento a una visualizzazione parziale per nome senza un'estensione di file, viene eseguita una ricerca nelle posizioni seguenti, nell'ordine indicato:When a partial view is referenced by name without a file extension, the following locations are searched in the stated order:

Razor PagesRazor Pages

  1. Cartella della pagina attualmente in esecuzioneCurrently executing page's folder
  2. Grafico delle directory sopra la cartella della paginaDirectory 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

Le convenzioni seguenti si applicano all'individuazione delle visualizzazioni parziali:The following conventions apply to partial view discovery:

  • Sono consentite visualizzazioni parziali diverse con lo stesso nome purché si trovino in cartelle diverse.Different partial views with the same file name are allowed when the partial views are in different folders.
  • Quando si fa riferimento a una visualizzazione parziale per nome senza un'estensione di file e la visualizzazione parziale è presente sia nella cartella del chiamante sia nella cartella Shared, viene usata la visualizzazione parziale nella cartella del chiamante.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. Se la visualizzazione parziale non è presente nella cartella del chiamante, viene usata la visualizzazione parziale nella cartella Shared.If the partial view isn't present in the caller's folder, the partial view is provided from the Shared folder. Le visualizzazioni parziali nella cartella Shared sono dette visualizzazioni parziali condivise o visualizzazioni parziali predefinite.Partial views in the Shared folder are called shared partial views or default partial views.
  • Le visualizzazioni parziali possono essere concatenate, che significa che una visualizzazione parziale può chiamarne un'altra se le chiamate non formano un riferimento circolare.Partial views can be chained—a partial view can call another partial view if a circular reference isn't formed by the calls. I percorsi relativi sono sempre relativi al file corrente, non alla radice o al padre del file.Relative paths are always relative to the current file, not to the root or parent of the file.

Nota

Un oggetto Razor section definito in una visualizzazione parziale non è visibile ai file di markup padre.A Razor section defined in a partial view is invisible to parent markup files. L'oggetto section è visibile solo per la visualizzazione parziale in cui è definito.The section is only visible to the partial view in which it's defined.

Accesso ai dati da visualizzazioni parzialiAccess data from partial views

Quando viene creata un'istanza di una visualizzazione parziale, riceve una copia del dizionario ViewData del padre.When a partial view is instantiated, it receives a copy of the parent's ViewData dictionary. Gli aggiornamenti apportati ai dati all'interno della visualizzazione parziale non vengono mantenuti per la visualizzazione padre.Updates made to the data within the partial view aren't persisted to the parent view. Le modifiche a ViewData in una visualizzazione parziale vengono perse quando viene restituita la visualizzazione parziale.ViewData changes in a partial view are lost when the partial view returns.

L'esempio seguente mostra come passare un'istanza di ViewDataDictionary a una visualizzazione parziale:The following example demonstrates how to pass an instance of ViewDataDictionary to a partial view:

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

È possibile trasmettere un modello in una visualizzazione parziale.You can pass a model into a partial view. Il modello può essere un oggetto personalizzato.The model can be a custom object. È possibile passare un modello con PartialAsync (esegue il rendering di un blocco di contenuto al chiamante) o con RenderPartialAsync (trasmette il contenuto all'output):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 PagesRazor Pages

Il markup seguente nella pagina di esempio è tratto dalla pagina Pages/ArticlesRP/ReadRP.cshtml.The following markup in the sample app is from the Pages/ArticlesRP/ReadRP.cshtml page. La pagina contiene due visualizzazioni parziali.The page contains two partial views. La seconda visualizzazione parziale viene trasmessa a un modello e ViewData viene trasmesso alla visualizzazione parziale.The second partial view passes in a model and ViewData to the partial view. L'overload del costruttore ViewDataDictionary viene usato per passare un nuovo dizionario ViewData mantenendo il dizionario ViewData esistente.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 è la prima visualizzazione parziale a cui fa riferimento il file di markup ReadRP.cshtml: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 è la seconda visualizzazione parziale a cui fa riferimento il file di markup ReadRP.cshtml: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

Il markup seguente nell'app di esempio mostra la visualizzazione Views/Articles/ReadRP.cshtml.The following markup in the sample app shows the Views/Articles/Read.cshtml view. La visualizzazione contiene due visualizzazioni parziali.The view contains two partial views. La seconda visualizzazione parziale viene trasmessa a un modello e ViewData viene trasmesso alla visualizzazione parziale.The second partial view passes in a model and ViewData to the partial view. L'overload del costruttore ViewDataDictionary viene usato per passare un nuovo dizionario ViewData mantenendo il dizionario ViewData esistente.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 è la prima visualizzazione parziale a cui fa riferimento il file di markup Read. cshtml :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 è la seconda visualizzazione parziale a cui fa riferimento il file di markup ReadRP.cshtml: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>

In fase di esecuzione, le visualizzazioni parziali vengono sottoposte a rendering nell'output sottoposto a rendering del file di markup, di cui viene a sua volta eseguito il rendering all'interno dell'elemento _Layout.cshtml condiviso.At runtime, the partials are rendered into the parent markup file's rendered output, which itself is rendered within the shared _Layout.cshtml. La prima visualizzazione parziale esegue il rendering del nome dell'autore e della data di pubblicazione dell'articolo:The first partial view renders the article author's name and publication date:

Abraham LincolnAbraham Lincoln

Questa visualizzazione parziale dal <percorso del file di visualizzazione parziale condivisa>.This partial view from <shared partial view file path>. 11/19/1863 12:00:00 AM11/19/1863 12:00:00 AM

La seconda visualizzazione parziale esegue il rendering delle sezioni dell'articolo: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 ...

Risorse aggiuntiveAdditional resources