使用 Razor ASP.NET Core 中的類別庫專案建立可重複使用的 UICreate reusable UI using the Razor class library project in ASP.NET Core

作者:Rick AndersonBy Rick Anderson

Razor您可以將視圖、頁面、控制器、頁面模型、 Razor 元件視圖元件和資料模型內建至 Razor 類別庫 (RCL) 。Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). RCL 可以封裝和重複使用。The RCL can be packaged and reused. 應用程式可以包括 RCL,以及覆寫它所包含的檢視和頁面。Applications can include the RCL and override the views and pages it contains. 當 web 應用程式和 RCL 中都有一個 view、partial view 或 Razor Page 時, Razor web 應用程式中) 的標記會優先使用 (的 cshtml 檔案。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.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

建立包含 UI 的類別庫 RazorCreate a class library containing Razor UI

  • 從 Visual Studio 選取 [ 建立新專案]。From Visual Studio select Create new a new project.
  • 選取 [ ** Razor 類別庫** > 下一步]Select Razor Class Library > Next.
  • 將程式庫命名 (例如," Razor ClassLib" ) > 建立]。Name the library (for example, "RazorClassLib"), > Create. 若要避免與產生的檢視程式庫發生檔案名稱衝突,程式庫名稱結尾請務必不要使用 .ViewsTo avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • 如果您需要支援 views,請選取 [ 支援頁面和視圖 ]。Select Support pages and views if you need to support views. 依預設,只 Razor 支援頁面。By default, only Razor Pages are supported. 選取 [建立]。Select Create.

Razor依預設,類別庫 (RCL) 範本預設為 Razor 元件開發。The Razor class library (RCL) template defaults to Razor component development by default. 支援頁面和 views選項支援頁面和視圖。The Support pages and views option supports pages and views.

將檔案新增 Razor 至 RCL。Add Razor files to the RCL.

ASP.NET Core 範本會假設 RCL 內容位於 [ 區域 ] 資料夾中。The ASP.NET Core templates assume the RCL content is in the Areas folder. 請參閱 RCL 頁面版面 配置來建立可公開內容的 RCL, ~/Pages 而不是 ~/Areas/PagesSee RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

參考 RCL 內容Reference RCL content

RCL 可以由下列各項參考:The RCL can be referenced by:

覆寫檢視、部分檢視和頁面Override views, partial views, and pages

當 web 應用程式和 RCL 中都有一個 view、partial view 或 Razor Page 時, Razor web 應用程式中) 的標記會優先使用 (的 cshtml 檔案。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. 例如,將 WebApp1/Areas/MyFeature/Pages/Page1. cshtml 新增至 WebApp1,WebApp1 中的 page1 將優先于 RCL 中的 page1。For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

在下載範例中,將 WebApp1/Areas/MyFeature2 重新命名為 WebApp1/Areas/MyFeature 以測試優先順序。In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

將* Razor UIClassLib/Areas/MyFeature/Pages/shared/_Message. cshtml* partial View 複製到WebApp1/Areas/MyFeature/pages/shared/_Message cshtmlCopy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. 更新標記來指示新的位置。Update the markup to indicate the new location. 建置並執行應用程式,以確認正在使用部分檢視的應用程式版本。Build and run the app to verify the app's version of the partial is being used.

RCL 頁面版面配置RCL Pages layout

若要參考 RCL 內容(如同 web 應用程式的 Pages 資料夾的一部分),請使用下列檔案結構來建立 RCL 專案: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/PagesRazorUIClassLib/Pages
  • RazorUIClassLib/Pages/SharedRazorUIClassLib/Pages/Shared

假設* Razor UIClassLib/Pages/Shared*包含兩個部分檔案: _Header cshtml_Footer. cshtmlSuppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. <partial>標記可新增至 _Layout 的cshtml檔案:The <partial> tags could be added to _Layout.cshtml file:

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

建立具有靜態資產的 RCLCreate an RCL with static assets

RCL 可能需要隨附的靜態資產,可由 RCL 或 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 可讓您建立 RCLs,其中包含可供取用應用程式使用的靜態資產。ASP.NET Core allows creating RCLs that include static assets that are available to a consuming app.

若要在 RCL 中包含隨附的資產,請在類別庫中建立 wwwroot 資料夾,並在該資料夾中包含任何必要的檔案。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.

封裝 RCL 時,[ wwwroot ] 資料夾中的所有隨附資產都會自動包含在套件中。When packing an RCL, all companion assets in the wwwroot folder are automatically included in the package.

使用 dotnet pack 命令,而不是 NuGet.exe 版本 nuget packUse the dotnet pack command rather than the NuGet.exe version nuget pack.

排除靜態資產Exclude static assets

若要排除靜態資產,請將所需的排除路徑新增至 $(DefaultItemExcludes) 專案檔中的屬性群組。To exclude static assets, add the desired exclusion path to the $(DefaultItemExcludes) property group in the project file. 以分號 () 分隔專案 ;Separate entries with a semicolon (;).

在下列範例中,[ wwwroot ] 資料夾中的lib樣式表單不會被視為靜態資產,且不會包含在已發佈的 RCL 中: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>

Typescript 整合Typescript integration

若要在 RCL 中包含 TypeScript 檔案:To include TypeScript files in an RCL:

  1. 將 TypeScript *檔案 () * 在 wwwroot 資料夾之外。Place the TypeScript files (.ts) outside of the wwwroot folder. 例如,將檔案放在 用戶端 資料夾中。For example, place the files in a Client folder.

  2. 設定 wwwroot 資料夾的 TypeScript 組建輸出。Configure the TypeScript build output for the wwwroot folder. 在專案檔中,于的 TypescriptOutDir 內設定屬性 PropertyGroupSet the TypescriptOutDir property inside of a PropertyGroup in the project file:

    <TypescriptOutDir>wwwroot</TypescriptOutDir>
    
  3. ResolveCurrentProjectStaticWebAssets在專案檔中的內新增下列目標,以將 TypeScript 目標納入為目標的相依性 PropertyGroupInclude 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>
    

使用參考 RCL 中的內容Consume content from a referenced RCL

RCL 的 wwwroot 資料夾中包含的檔案會公開給 RCL 或使用中的應用程式(前置詞下) _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}/. 例如,名為的程式庫* Razor 。類別 .Lib*會產生靜態內容的路徑 _content/Razor.Class.Lib/For example, a library named Razor.Class.Lib results in a path to static content at _content/Razor.Class.Lib/. 當產生 NuGet 封裝且元件名稱與封裝識別碼不同時,請使用的封裝識別碼 {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}.

取用應用程式會參考程式庫透過 <script><style><img> 和其他 HTML 標籤所提供的靜態資產。The consuming app references static assets provided by the library with <script>, <style>, <img>, and other HTML tags. 使用中的應用程式必須在中啟用 靜態檔案支援 Startup.ConfigureThe consuming app must have static file support enabled in Startup.Configure:

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

    app.UseStaticFiles();

    ...
}

從組建輸出 () 執行取用應用程式時 dotnet run ,預設會在開發環境中啟用靜態 web 資產。When running the consuming app from build output (dotnet run), static web assets are enabled by default in the Development environment. 若要在從組建輸出執行時支援其他環境中的資產,請在 UseStaticWebAssets 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>();
            });
}

UseStaticWebAssets從已發行的輸出 () 執行應用程式時,不需要呼叫 dotnet publishCalling UseStaticWebAssets isn't required when running an app from published output (dotnet publish).

多專案開發流程Multi-project development flow

使用中的應用程式執行時:When the consuming app runs:

  • RCL 中的資產會留在其原始檔案夾中。The assets in the RCL stay in their original folders. 資產不會移至使用中的應用程式。The assets aren't moved to the consuming app.
  • RCL 的 wwwroot 資料夾內的任何變更,都會在重建 RCL 之後,而不重建取用應用程式時,反映在取用應用程式中。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.

建立 RCL 時,會產生資訊清單來描述靜態 web 資產位置。When the RCL is built, a manifest is produced that describes the static web asset locations. 取用應用程式會在執行時間讀取資訊清單,以取用參考專案和套件中的資產。The consuming app reads the manifest at runtime to consume the assets from referenced projects and packages. 當新的資產新增至 RCL 時,必須重建 RCL,才能在取用應用程式存取新資產之前更新其資訊清單。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.

發佈Publish

當應用程式發佈時,所有參考專案和套件中的隨附資產都會複製到下所發佈應用程式的 [ wwwroot ] 資料夾中 _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}/.

Razor您可以將視圖、頁面、控制器、頁面模型、 Razor 元件視圖元件和資料模型內建至 Razor 類別庫 (RCL) 。Razor views, pages, controllers, page models, Razor components, View components, and data models can be built into a Razor class library (RCL). RCL 可以封裝和重複使用。The RCL can be packaged and reused. 應用程式可以包括 RCL,以及覆寫它所包含的檢視和頁面。Applications can include the RCL and override the views and pages it contains. 當 web 應用程式和 RCL 中都有一個 view、partial view 或 Razor Page 時, Razor web 應用程式中) 的標記會優先使用 (的 cshtml 檔案。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.

查看或下載範例程式碼 (如何下載) View or download sample code (how to download)

建立包含 UI 的類別庫 RazorCreate a class library containing Razor UI

  • 從 Visual Studio 的 [檔案]**** 功能表中,選取 [新增][專案] > **** 。From the Visual Studio File menu, select New > Project.
  • 選取 ASP.NET Core Web 應用程式Select ASP.NET Core Web Application.
  • 將程式庫命名 (例如 " Razor ClassLib" ) > 確定]Name the library (for example, "RazorClassLib") > OK. 若要避免與產生的檢視程式庫發生檔案名稱衝突,程式庫名稱結尾請務必不要使用 .ViewsTo avoid a file name collision with the generated view library, ensure the library name doesn't end in .Views.
  • 確認已選取 ASP.NET Core 2.1 或更新版本。Verify ASP.NET Core 2.1 or later is selected.
  • 選取 [ ** Razor 類別庫** > 確定]Select Razor Class Library > OK.

RCL 具有下列專案檔案: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>

將檔案新增 Razor 至 RCL。Add Razor files to the RCL.

ASP.NET Core 範本會假設 RCL 內容位於 [ 區域 ] 資料夾中。The ASP.NET Core templates assume the RCL content is in the Areas folder. 請參閱 RCL 頁面版面 配置來建立可公開內容的 RCL, ~/Pages 而不是 ~/Areas/PagesSee RCL Pages layout to create an RCL that exposes content in ~/Pages rather than ~/Areas/Pages.

參考 RCL 內容Reference RCL content

RCL 可以由下列各項參考:The RCL can be referenced by:

逐步解說:建立 RCL 專案並使用於 Razor 頁面專案中Walkthrough: Create an RCL project and use from a Razor Pages project

您可以下載完整專案並測試它,而不是建立它。You can download the complete project and test it rather than creating it. 下載範例包含額外的程式碼和連結,讓您輕鬆地測試專案。The sample download contains additional code and links that make the project easy to test. 您可以在此 GitHub 問題留下意見反應以及您對下載範例與逐步指示的評論。You can leave feedback in this GitHub issue with your comments on download samples versus step-by-step instructions.

測試下載應用程式Test the download app

如果您尚未下載已完成的應用程式,而是要建立逐步解說專案,請跳至下一節If you haven't downloaded the completed app and would rather create the walkthrough project, skip to the next section.

在 Visual Studio 中開啟 .sln 檔案。Open the .sln file in Visual Studio. 執行應用程式。Run the app.

遵循測試 WebApp1 中的指示執行。Follow the instructions in Test WebApp1

建立 RCLCreate an RCL

本節會建立 RCL。In this section, an RCL is created. Razor 檔案會新增至 RCL。Razor files are added to the RCL.

建立 RCL 專案:Create the RCL project:

  • 從 Visual Studio 的 [檔案]**** 功能表中,選取 [新增][專案] > **** 。From the Visual Studio File menu, select New > Project.
  • 選取 ASP.NET Core Web 應用程式Select ASP.NET Core Web Application.
  • 將應用程式命名為** Razor UIClassLib** > OKName the app RazorUIClassLib > OK.
  • 確認已選取 ASP.NET Core 2.1 或更新版本。Verify ASP.NET Core 2.1 or later is selected.
  • 選取 [ ** Razor 類別庫** > 確定]Select Razor Class Library > OK.
  • 加入 Razor 名為* Razor UIClassLib/Areas/MyFeature/Pages/Shared/_Message*的部分視圖檔案。Add a Razor partial view file named RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml.

將檔案 Razor 和資料夾加入至專案Add Razor files and folders to the project

  • 將* Razor UIClassLib/Areas/MyFeature/Pages/Shared/_Message*中的標記取代為下列程式碼: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>
    
  • 將* Razor UIClassLib/Areas/MyFeature/Pages/Page1. cshtml*中的標記取代為下列程式碼: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 才能使用部分檢視 (<partial name="_Message" />)。@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers is required to use the partial view (<partial name="_Message" />). 您可以新增 _ViewImports.cshtml 檔案,而不要包含 @addTagHelper 指示詞。Rather than including the @addTagHelper directive, you can add a _ViewImports.cshtml file. 例如:For example:

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

    如需有關 _ViewImports 的詳細資訊,請參閱匯入共用指示詞 For more information on _ViewImports.cshtml, see Importing Shared Directives

  • 建置類別庫,以確認沒有任何編譯器錯誤:Build the class library to verify there are no compiler errors:

    dotnet build RazorUIClassLib
    

組建輸出包含* RazorUIClassLib.dll RazorUIClassLib.Views.dll*。The build output contains RazorUIClassLib.dll and RazorUIClassLib.Views.dll. * RazorUIClassLib.Views.dll*包含已編譯的 Razor 內容。RazorUIClassLib.Views.dll contains the compiled Razor content.

使用 Razor 頁面專案的 UI 程式庫 RazorUse the Razor UI library from a Razor Pages project

建立 Razor 頁面 web 應用程式:Create the Razor Pages web app:

  • 在 [方案總管]**** 中,以滑鼠右鍵按一下解決方案 > [新增][新增專案] > ****。From Solution Explorer, right-click the solution > Add > New Project.

  • 選取 ASP.NET Core Web 應用程式Select ASP.NET Core Web Application.

  • 將應用程式命名為 WebApp1Name the app WebApp1.

  • 確認已選取 ASP.NET Core 2.1 或更新版本。Verify ASP.NET Core 2.1 or later is selected.

  • 選取 [Web 應用程式][確定] > ****。Select Web Application > OK.

  • 從 [方案總管]****,以滑鼠右鍵按一下 WebApp1,然後選取 [設定為啟始專案]****。From Solution Explorer, right-click on WebApp1 and select Set as StartUp Project.

  • 從方案總管****,以滑鼠右鍵按一下 WebApp1,然後選取 [建置相依性][專案相依性] > ****。From Solution Explorer, right-click on WebApp1 and select Build Dependencies > Project Dependencies.

  • 檢查** Razor UIClassLib是否為WebApp1**的相依性。Check RazorUIClassLib as a dependency of WebApp1.

  • 從 [方案總管]****,以滑鼠右鍵按一下 WebApp1,然後選取 [新增][參考] > ****。From Solution Explorer, right-click on WebApp1 and select Add > Reference.

  • 在 [參考管理員] 對話方塊中,檢查** Razor UIClassLib** > 確定In the Reference Manager dialog, check RazorUIClassLib > OK.

執行應用程式。Run the app.

測試 WebApp1Test WebApp1

流覽至, /MyFeature/Page1 確認 Razor UI 類別庫正在使用中。Browse to /MyFeature/Page1 to verify that the Razor UI class library is in use.

覆寫檢視、部分檢視和頁面Override views, partial views, and pages

當 web 應用程式和 RCL 中都有一個 view、partial view 或 Razor Page 時, Razor web 應用程式中) 的標記會優先使用 (的 cshtml 檔案。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. 例如,將 WebApp1/Areas/MyFeature/Pages/Page1. cshtml 新增至 WebApp1,WebApp1 中的 page1 將優先于 RCL 中的 page1。For example, add WebApp1/Areas/MyFeature/Pages/Page1.cshtml to WebApp1, and Page1 in the WebApp1 will take precedence over Page1 in the RCL.

在下載範例中,將 WebApp1/Areas/MyFeature2 重新命名為 WebApp1/Areas/MyFeature 以測試優先順序。In the sample download, rename WebApp1/Areas/MyFeature2 to WebApp1/Areas/MyFeature to test precedence.

將* Razor UIClassLib/Areas/MyFeature/Pages/shared/_Message. cshtml* partial View 複製到WebApp1/Areas/MyFeature/pages/shared/_Message cshtmlCopy the RazorUIClassLib/Areas/MyFeature/Pages/Shared/_Message.cshtml partial view to WebApp1/Areas/MyFeature/Pages/Shared/_Message.cshtml. 更新標記來指示新的位置。Update the markup to indicate the new location. 建置並執行應用程式,以確認正在使用部分檢視的應用程式版本。Build and run the app to verify the app's version of the partial is being used.

RCL 頁面版面配置RCL Pages layout

若要參考 RCL 內容(如同 web 應用程式的 Pages 資料夾的一部分),請使用下列檔案結構來建立 RCL 專案: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/PagesRazorUIClassLib/Pages
  • RazorUIClassLib/Pages/SharedRazorUIClassLib/Pages/Shared

假設* Razor UIClassLib/Pages/Shared*包含兩個部分檔案: _Header cshtml_Footer. cshtmlSuppose RazorUIClassLib/Pages/Shared contains two partial files: _Header.cshtml and _Footer.cshtml. <partial>標記可新增至 _Layout 的cshtml檔案:The <partial> tags could be added to _Layout.cshtml file:

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

其他資源Additional resources