Creare un'interfaccia utente riutilizzabile usando il Razor progetto libreria di classi in ASP.NET CoreCreate reusable UI using the Razor class library project in ASP.NET Core

Autore: Rick AndersonBy Rick Anderson

Razorle visualizzazioni, le pagine, i controller, i modelli di pagina, i Razor componenti, i componenti di visualizzazionee i modelli di dati possono essere incorporati in una Razor libreria di classi (RCL).Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). La libreria di classi Razor può essere inclusa nel pacchetto e usata nuovamente.The RCL can be packaged and reused. Le applicazioni possono includere la libreria di classi Razor ed eseguire l'override delle visualizzazioni e pagine in essa contenute.Applications can include the RCL and override the views and pages it contains. Quando si trova una visualizzazione, una visualizzazione parziale o una Razor pagina nell'app Web e nel RCL, il Razor markup (file conestensione cshtml ) nell'app Web ha la precedenza.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence.

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

Creare una libreria di classi contenente l' Razor interfaccia utenteCreate a class library containing Razor UI

  • In Visual Studio selezionare Crea nuovo nuovo progetto.From Visual Studio select Create new a new project.
  • Selezionare ** Razor libreria di classi** > Avanti.Select Razor Class Library > Next.
  • Assegnare un nome alla libreria (ad esempio, " Razor CLASSLIB") > creare.Name the library (for example, "RazorClassLib"), > Create. Per evitare un conflitto di nomi di file con la libreria di visualizzazione generata, verificare che il nome della libreria non finisca per .Views.To avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • Se è necessario supportare le visualizzazioni, selezionare pagine e visualizzazioni di supporto .Select Support pages and views if you need to support views. Per impostazione predefinita, Razor sono supportate solo le pagine.By default, only Razor Pages are supported. Selezionare Create (Crea).Select Create.

Per impostazione predefinita, il Razor modello libreria di classi (RCL) prevede Razor lo sviluppo di componenti.The Razor class library (RCL) template defaults to Razor component development by default. L'opzione pagine e visualizzazioni di supporto supporta pagine e viste.The Support pages and views option supports pages and views.

Aggiungere Razor i file a RCL.Add Razor files to the RCL.

I modelli di ASP.NET Core presuppongono che il contenuto RCL si trovi nella cartella aree .The ASP.NET Core templates assume the RCL content is in the Areas folder. Vedere layout di pagine RCL per creare un RCL che espone il contenuto in ~/Pages anziché ~/Areas/Pages .See RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

Contenuto RCL di riferimentoReference RCL content

Il riferimento alla libreria di classi Razor può essere eseguito da:The RCL can be referenced by:

Eseguire l'override di visualizzazioni, visualizzazioni parziali e pagineOverride views, partial views, and pages

Quando si trova una visualizzazione, una visualizzazione parziale o una Razor pagina nell'app Web e nel RCL, il Razor markup (file conestensione cshtml ) nell'app Web ha la precedenza.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence. Ad esempio, aggiungere app Web 1/areas/la funzionalità/Pages/Pagina1. cshtml a app Web 1 e Pagina1 in app Web 1 avrà la precedenza su PAGINA1 in RCL.For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

Nel download di esempio, rinominare WebApp1/aree/MyFeature2 in WebApp1/aree/MyFeature per testare la precedenza.In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

Copiare la visualizzazione parziale * Razor UIClassLib/areas/la funzionalità/Pages/Shared/_Message. cshtml* in app Web 1/areas/my feature/pages/Shared/_Message. cshtml.Copy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aggiornare il markup per indicare la nuova posizione.Update the markup to indicate the new location. Compilare ed eseguire l'app per verificare quale versione del parziale sia in uso.Build and run the app to verify the app's version of the partial is being used.

Layout di pagine RCLRCL Pages layout

Per fare riferimento al contenuto RCL come se facesse parte della cartella pagine dell'app Web, creare il progetto RCL con la struttura di file seguente:To reference RCL content as though it is part of the web app's Pages folder, create the RCL project with the following file structure:

  • RazorUIClassLib/pagineRazorUIClassLib/Pages
  • RazorUIClassLib/pagine/condivisoRazorUIClassLib/Pages/Shared

Si supponga che * Razor UIClassLib/Pages/Shared* contenga due file parziali: _Header. cshtml e _Footer. cshtml.Suppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. <partial>È possibile aggiungere i tag al file _Layout. cshtml :The <partial> tags could be added to _Layout.cshtml file:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Creare un RCL con asset staticiCreate an RCL with static assets

Un RCL può richiedere risorse statiche complementari a cui è possibile fare riferimento tramite il RCL o l'app consumer di RCL.An RCL may require companion static assets that can be referenced by either the RCL or the consuming app of the RCL. ASP.NET Core consente di creare RCL che includono risorse statiche disponibili per un'app di consumo.ASP.NET Core allows creating RCLs that include static assets that are available to a consuming app.

Per includere asset complementari come parte di un RCL, creare una cartella wwwroot nella libreria di classi e includere tutti i file necessari in tale cartella.To include companion assets as part of an RCL, create a wwwroot folder in the class library and include any required files in that folder.

Quando si esegue la compressione di un RCL, tutti gli asset complementari nella cartella wwwroot vengono inclusi automaticamente nel pacchetto.When packing an RCL, all companion assets in the wwwroot folder are automatically included in the package.

Usare il dotnet pack comando anziché la versione NuGet.exe nuget pack .Use the dotnet pack command rather than the NuGet.exe version nuget pack.

Escludi asset staticiExclude static assets

Per escludere asset statici, aggiungere il percorso di esclusione desiderato al $(DefaultItemExcludes) gruppo di proprietà nel file di progetto.To exclude static assets, add the desired exclusion path to the $(DefaultItemExcludes) property group in the project file. Separare le voci con un punto e virgola ( ; ).Separate entries with a semicolon (;).

Nell'esempio seguente, il foglio di stile lib. CSS nella cartella wwwroot non è considerato un asset statico e non è incluso nel RCL pubblicato:In the following example, the lib.css stylesheet in the wwwroot folder isn't considered a static asset and isn't included in the published RCL:

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);wwwroot\lib.css</DefaultItemExcludes>
</PropertyGroup>

Integrazione typescriptTypescript integration

Per includere i file TypeScript in un RCL:To include TypeScript files in an RCL:

  1. Inserire i file TypeScript (. TS) all'esterno della cartella wwwrootPlace the TypeScript files (.ts) outside of the wwwroot folder. Inserire, ad esempio, i file in una cartella client .For example, place the files in a Client folder.

  2. Configurare l'output di compilazione TypeScript per la cartella wwwroot .Configure the TypeScript build output for the wwwroot folder. Impostare la TypescriptOutDir proprietà all'interno di un oggetto PropertyGroup nel file di progetto:Set the TypescriptOutDir property inside of a PropertyGroup in the project file:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>
    
  3. Includere la destinazione TypeScript come dipendenza della destinazione aggiungendo ResolveCurrentProjectStaticWebAssets la destinazione seguente all'interno di un oggetto PropertyGroup nel file di progetto:Include the TypeScript target as a dependency of the ResolveCurrentProjectStaticWebAssets target by adding the following target inside of a PropertyGroup in the project file:

    <ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
      CompileTypeScript;
      $(ResolveCurrentProjectStaticWebAssetsInputs)
    </ResolveCurrentProjectStaticWebAssetsInputsDependsOn>
    

Utilizzare il contenuto da un RCL a cui si fa riferimentoConsume content from a referenced RCL

I file inclusi nella cartella wwwroot di RCL vengono esposti a RCL o all'app consumer sotto il prefisso _content/{LIBRARY NAME}/ .The files included in the wwwroot folder of the RCL are exposed to either the RCL or the consuming app under the prefix _content/{LIBRARY NAME}/. Ad esempio, una libreria denominata * Razor . Class. lib* restituisce un percorso al contenuto statico in _content/Razor.Class.Lib/ .For example, a library named Razor.Class.Lib results in a path to static content at _content/Razor.Class.Lib/. Quando si produce un pacchetto NuGet e il nome dell'assembly non è uguale all'ID del pacchetto, usare l'ID del pacchetto per {LIBRARY NAME} .When producing a NuGet package and the assembly name isn't the same as the package ID, use the package ID for {LIBRARY NAME}.

L'app consumer fa riferimento a risorse statiche fornite dalla libreria con <script> ,, <style> <img> e altri tag HTML.The consuming app references static assets provided by the library with <script>, <style>, <img>, and other HTML tags. Per l'app consumer deve essere abilitato il supporto file statico in Startup.Configure :The consuming app must have static file support enabled in Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    ...

    app.UseStaticFiles();

    ...
}

Quando si esegue l'app consumer dall'output di compilazione ( dotnet run ), le risorse Web statiche sono abilitate per impostazione predefinita nell'ambiente di sviluppo.When running the consuming app from build output (dotnet run), static web assets are enabled by default in the Development environment. Per supportare asset in altri ambienti durante l'esecuzione dall'output di compilazione, chiamare UseStaticWebAssets sul generatore host in Program.cs:To support assets in other environments when running from build output, call UseStaticWebAssets on the host builder in Program.cs:

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

UseStaticWebAssetsQuando si esegue un'app dall'output pubblicato (), la chiamata non è obbligatoria dotnet publish .Calling UseStaticWebAssets isn't required when running an app from published output (dotnet publish).

Flusso di sviluppo per più progettiMulti-project development flow

Quando viene eseguita l'app consumer:When the consuming app runs:

  • Gli asset nel RCL rimanere nelle cartelle originali.The assets in the RCL stay in their original folders. Gli asset non vengono spostati nell'app consumer.The assets aren't moved to the consuming app.
  • Tutte le modifiche apportate all'interno della cartella wwwroot di RCL vengono riflesse nell'app consumer dopo che il RCL viene ricompilato e senza ricompilare l'app consumer.Any change within the RCL's wwwroot folder is reflected in the consuming app after the RCL is rebuilt and without rebuilding the consuming app.

Quando viene compilato il RCL, viene generato un manifesto che descrive i percorsi di asset Web statici.When the RCL is built, a manifest is produced that describes the static web asset locations. L'app consumer legge il manifesto in fase di esecuzione per usare gli asset dei progetti e dei pacchetti a cui si fa riferimento.The consuming app reads the manifest at runtime to consume the assets from referenced projects and packages. Quando si aggiunge un nuovo asset a un RCL, è necessario ricompilare il RCL per aggiornare il manifesto prima che un'app che utilizza possa accedere al nuovo asset.When a new asset is added to an RCL, the RCL must be rebuilt to update its manifest before a consuming app can access the new asset.

PubblicaPublish

Quando viene pubblicata l'app, gli asset complementari di tutti i progetti e i pacchetti a cui viene fatto riferimento vengono copiati nella cartella wwwroot dell'app pubblicata in _content/{LIBRARY NAME}/ .When the app is published, the companion assets from all referenced projects and packages are copied into the wwwroot folder of the published app under _content/{LIBRARY NAME}/.

Razorle visualizzazioni, le pagine, i controller, i modelli di pagina, i Razor componenti, i componenti di visualizzazionee i modelli di dati possono essere incorporati in una Razor libreria di classi (RCL).Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). La libreria di classi Razor può essere inclusa nel pacchetto e usata nuovamente.The RCL can be packaged and reused. Le applicazioni possono includere la libreria di classi Razor ed eseguire l'override delle visualizzazioni e pagine in essa contenute.Applications can include the RCL and override the views and pages it contains. Quando si trova una visualizzazione, una visualizzazione parziale o una Razor pagina nell'app Web e nel RCL, il Razor markup (file conestensione cshtml ) nell'app Web ha la precedenza.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence.

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

Creare una libreria di classi contenente l' Razor interfaccia utenteCreate a class library containing Razor UI

  • Dal menu File di Visual Studio selezionare Nuovo > Progetto.From the Visual Studio File menu, select New > Project.
  • Selezionare Applicazione Web ASP.NET Core.Select ASP.NET Core Web Application.
  • Assegnare un nome alla libreria (ad esempio, " Razor CLASSLIB") > OK.Name the library (for example, "RazorClassLib") > OK. Per evitare un conflitto di nomi di file con la libreria di visualizzazione generata, verificare che il nome della libreria non finisca per .Views.To avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • Verificare che sia selezionato ASP.NET Core 2.1 o versioni successive.Verify ASP.NET Core 2.1 or later is selected.
  • Selezionare ** Razor libreria di classi** > OK.Select Razor Class Library > OK.

Un RCL ha il seguente file di progetto:An RCL has the following project file:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Aggiungere Razor i file a RCL.Add Razor files to the RCL.

I modelli di ASP.NET Core presuppongono che il contenuto RCL si trovi nella cartella aree .The ASP.NET Core templates assume the RCL content is in the Areas folder. Vedere layout di pagine RCL per creare un RCL che espone il contenuto in ~/Pages anziché ~/Areas/Pages .See RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

Contenuto RCL di riferimentoReference RCL content

Il riferimento alla libreria di classi Razor può essere eseguito da:The RCL can be referenced by:

Procedura dettagliata: creare un progetto RCL e usarlo da un Razor progetto PagesWalkthrough: Create an RCL project and use from a Razor Pages project

È possibile scaricare il progetto completo e testarlo anziché crearlo.You can download the complete project and test it rather than creating it. Il download di esempio contiene codice aggiuntivo e collegamenti che rendono più semplice testare il progetto.The sample download contains additional code and links that make the project easy to test. È possibile lasciare commenti e suggerimenti in questa discussione su GitHub con i commenti sui download di esempio rispetto alle istruzioni dettagliate.You can leave feedback in this GitHub issue with your comments on download samples versus step-by-step instructions.

Testare l'app di downloadTest the download app

Se non è stata scaricata l'app completa e si vuole invece creare il progetto della procedura dettagliata, passare alla prossima sezione.If you haven't downloaded the completed app and would rather create the walkthrough project, skip to the next section.

Aprire il file con estensione sln in Visual Studio.Open the .sln file in Visual Studio. Eseguire l'app.Run the app.

Seguire le istruzioni indicate in Testare WebApp1Follow the instructions in Test WebApp1

Creare un RCLCreate an RCL

In questa sezione viene creato un RCL.In this section, an RCL is created. Razor i file vengono aggiunti a RCL.Razor files are added to the RCL.

Creare il progetto di libreria di classi Razor:Create the RCL project:

  • Dal menu File di Visual Studio selezionare Nuovo > Progetto.From the Visual Studio File menu, select New > Project.
  • Selezionare Applicazione Web ASP.NET Core.Select ASP.NET Core Web Application.
  • Denominare l'app ** Razor UIClassLib** > OK.Name the app RazorUIClassLib > OK.
  • Verificare che sia selezionato ASP.NET Core 2.1 o versioni successive.Verify ASP.NET Core 2.1 or later is selected.
  • Selezionare ** Razor libreria di classi** > OK.Select Razor Class Library > OK.
  • Aggiungere un Razor file di visualizzazione parziale denominato * Razor UIClassLib/areas/la funzionalità/Pages/Shared/_Message. cshtml*.Add a Razor partial view file named RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.

Aggiungere Razor file e cartelle al progettoAdd Razor files and folders to the project

  • Sostituire il markup in * Razor UIClassLib/areas/la funzionalità/Pages/Shared/_Message. cshtml* con il codice seguente:Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml with the following code:

    <h3>_Message.cshtml partial view.</h3>
    
    <p>RazorUIClassLib\Areas\MyFeature\Pages\Shared\_Message.cshtml</p>
    
  • Sostituire il markup in * Razor UIClassLib/areas/la funzionalità/Pages/Pagina1. cshtml* con il codice seguente:Replace the markup in RazorUIClassLib/Areas/MyFeature/Pages/Page1.cshtml with the following code:

    @page
    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
    
    <h2>Hello from a Razor UI class library!</h2>
    <p> From  RazorUIClassLib\Areas\MyFeature\Pages\Page1.cshtml</p>
    
    <partial name="_Message" />
    

    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers è necessario per usare la visualizzazione parziale (<partial name="_Message" />).@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers is required to use the partial view (<partial name="_Message" />). Anziché includere la direttiva @addTagHelper, è possibile aggiungere un file _ViewImports.cshtml.Rather than including the @addTagHelper directive, you can add a _ViewImports.cshtml file. Ad esempio:For example:

    dotnet new viewimports -o RazorUIClassLib/Areas/MyFeature/Pages
    

    Per altre informazioni su _ViewImports. cshtml, vedere importazione di direttive condiviseFor more information on _ViewImports.cshtml, see Importing Shared Directives

  • Compilare la libreria di classi per verificare che non siano presenti errori del compilatore:Build the class library to verify there are no compiler errors:

    dotnet build RazorUIClassLib
    

L'output di compilazione contiene * RazorUIClassLib.dll* e * RazorUIClassLib.Views.dll*.The build output contains RazorUIClassLib.dll and RazorUIClassLib.Views.dll. * RazorUIClassLib.Views.dll* contiene il Razor contenuto compilato.RazorUIClassLib.Views.dll contains the compiled Razor content.

Usare la Razor libreria dell'interfaccia utente da un Razor progetto di pagineUse the Razor UI library from a Razor Pages project

Creare l' Razor app Web Pages:Create the Razor Pages web app:

  • In Esplora soluzioni fare clic con il pulsante destro del mouse sulla soluzione > Aggiungi > Nuovo progetto.From Solution Explorer, right-click the solution > Add > New Project.

  • Selezionare Applicazione Web ASP.NET Core.Select ASP.NET Core Web Application.

  • Denominare l'app WebApp1.Name the app WebApp1.

  • Verificare che sia selezionato ASP.NET Core 2.1 o versioni successive.Verify ASP.NET Core 2.1 or later is selected.

  • Selezionare Applicazione Web > OK.Select Web Application > OK.

  • In Esplora soluzioni fare clic con il pulsante destro del mouse su WebApp1 e selezionare Imposta come progetto di avvio.From Solution Explorer, right-click on WebApp1 and select Set as StartUp Project.

  • In Esplora soluzioni fare clic con il pulsante destro del mouse su WebApp1 e selezionare Dipendenze di compilazione > Dipendenze progetto.From Solution Explorer, right-click on WebApp1 and select Build Dependencies > Project Dependencies.

  • Controllare ** Razor UIClassLib** come dipendenza di app Web 1.Check RazorUIClassLib as a dependency of WebApp1.

  • In Esplora soluzioni fare clic con il pulsante destro del mouse su WebApp1 e scegliere Aggiungi > Riferimento.From Solution Explorer, right-click on WebApp1 and select Add > Reference.

  • Nella finestra di dialogo Gestione riferimenti selezionare ** Razor UIClassLib** > OK.In the Reference Manager dialog, check RazorUIClassLib > OK.

Eseguire l'app.Run the app.

Testare WebApp1Test WebApp1

Passare a /MyFeature/Page1 per verificare che la Razor libreria di classi dell'interfaccia utente sia in uso.Browse to /MyFeature/Page1 to verify that the Razor UI class library is in use.

Eseguire l'override di visualizzazioni, visualizzazioni parziali e pagineOverride views, partial views, and pages

Quando si trova una visualizzazione, una visualizzazione parziale o una Razor pagina nell'app Web e nel RCL, il Razor markup (file conestensione cshtml ) nell'app Web ha la precedenza.When a view, partial view, or Razor Page is found in both the web app and the RCL, the Razor markup (.cshtml file) in the web app takes precedence. Ad esempio, aggiungere app Web 1/areas/la funzionalità/Pages/Pagina1. cshtml a app Web 1 e Pagina1 in app Web 1 avrà la precedenza su PAGINA1 in RCL.For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

Nel download di esempio, rinominare WebApp1/aree/MyFeature2 in WebApp1/aree/MyFeature per testare la precedenza.In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

Copiare la visualizzazione parziale * Razor UIClassLib/areas/la funzionalità/Pages/Shared/_Message. cshtml* in app Web 1/areas/my feature/pages/Shared/_Message. cshtml.Copy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. Aggiornare il markup per indicare la nuova posizione.Update the markup to indicate the new location. Compilare ed eseguire l'app per verificare quale versione del parziale sia in uso.Build and run the app to verify the app's version of the partial is being used.

Layout di pagine RCLRCL Pages layout

Per fare riferimento al contenuto RCL come se facesse parte della cartella pagine dell'app Web, creare il progetto RCL con la struttura di file seguente:To reference RCL content as though it is part of the web app's Pages folder, create the RCL project with the following file structure:

  • RazorUIClassLib/pagineRazorUIClassLib/Pages
  • RazorUIClassLib/pagine/condivisoRazorUIClassLib/Pages/Shared

Si supponga che * Razor UIClassLib/Pages/Shared* contenga due file parziali: _Header. cshtml e _Footer. cshtml.Suppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. <partial>È possibile aggiungere i tag al file _Layout. cshtml :The <partial> tags could be added to _Layout.cshtml file:

<body>
  <partial name="_Header">
  @RenderBody()
  <partial name="_Footer">
</body>

Risorse aggiuntiveAdditional resources