Razor 类库(Razor Class Library)Hello World 实战:在 ASP.NET Core 中构建可复用的 UI 组件库
Razor 类库(Razor Class Library)Hello World 实战:在 ASP.NET Core 中构建可复用的 UI 组件库
本文以 practical-aspnetcore 仓库中的 razor-class-library-1 示例 为核心,系统讲解如何在 ASP.NET Core 中使用 Razor 类库(Razor Class Library,简称 RCL)把页面、视图等 UI 组件封装成独立类库,并通过项目引用的方式接入主 Web 应用。读完本文,你将掌握 RCL 的完整创建命令、.csproj 关键配置、Razor Pages 在类库中的目录组织方式,以及宿主应用如何映射并访问类库提供的页面。
一、什么是 Razor 类库(RCL)
Razor 类库是 ASP.NET Core 提供的一种基于 Microsoft.NET.Sdk.Razor SDK 的类库项目。它的核心价值在于:可以把 Razor 页面、MVC 视图、Tag Helper、静态资源(CSS/JS/图片)等 UI 资产打包成一个独立的程序集,供多个应用共享复用,从而避免在多个 Web 项目之间复制粘贴相同的页面代码。
在该仓库中,RCL 是 projects/mvc/razor-class-library 章节的探索主题(见章节 README),包含三个递进式示例:
| 示例 | 目录 | 主题 |
|---|---|---|
| Razor Class Library - Hello World | razor-class-library-1 | 最简示例,类库中使用 Razor Pages |
| Razor Class Library - Include static files | razor-class-library-with-static-files | 在 RCL 中附带 JavaScript、图片、CSS 等静态文件 |
| Razor Class Library - using Controllers and Views | razor-class-library-with-controllers | 在 RCL 中使用 MVC 的 Controller 与 View |
本文聚焦第一个 Hello World 示例,后两个示例将在文末作为延伸路径简要说明。
二、示例项目的整体结构
razor-class-library-1 的完整源码位于仓库的 projects/mvc/razor-class-library/razor-class-library-1/src 目录下,共包含三个项目:
src/
├── RazorClassLibrary1/
│ ├── Areas/
│ │ └── Module1/
│ │ └── Pages/
│ │ ├── Index.cshtml
│ │ └── Index.cshtml.cs
│ └── RazorClassLibrary1.csproj
├── RazorClassLibrary2/
│ ├── Areas/
│ │ └── Module2/
│ │ └── Pages/
│ │ ├── Index.cshtml
│ │ └── Index.cshtml.cs
│ └── RazorClassLibrary2.csproj
└── WebApplication/
├── Program.cs
├── WebApplication.csproj
├── appsettings.json
└── appsettings.Development.json
可以看出,这是一个"两个类库 + 一个宿主 Web 应用"的经典组合:
- RazorClassLibrary1:在
Areas/Module1/Pages下提供首页; - RazorClassLibrary2:在
Areas/Module2/Pages下提供首页; - WebApplication:引用上述两个类库,作为宿主应用对外提供访问入口。
RCL 中利用 Area(区域) 来隔离不同类库的页面命名空间与路由,是防止多个类库之间路由冲突的常用做法。
三、从零创建:完整命令清单
原 README 给出了从零搭建该示例的全部命令(见 razor-class-library-1/README.md),下面是逐条展开的版本。按文档作者的约定,所有命令在项目的 src 目录下执行(对应仓库中的 src/ 子目录):
# 1. 进入源码目录
cd /src
# 2. 创建两个 Razor 类库项目
dotnet new razorclasslib -n RazorClassLibrary1
dotnet new razorclasslib -n RazorClassLibrary2
# 3. 创建一个空的 Web 应用作为宿主
dotnet new web -n WebApplication
# 4. 让 Web 应用同时引用两个类库
dotnet add WebApplication/WebApplication.csproj reference RazorClassLibrary1/RazorClassLibrary1.csproj RazorClassLibrary2/RazorClassLibrary2.csproj
# 5. 在类库 1 中通过 Razor Pages 模板创建 Index 页面,放入 Areas/Module1/Pages 目录
cd RazorClassLibrary1
dotnet new page -n Index -o Areas/Module1/Pages
cd ../
# 6. 在类库 2 中做同样的操作,放入 Areas/Module2/Pages 目录
cd RazorClassLibrary2
dotnet new page -n Index -o Areas/Module2/Pages
cd ../
命令要点说明:
dotnet new razorclasslib:Razor 类库的项目模板。生成的.csproj使用Microsoft.NET.Sdk.RazorSDK,默认已含_ViewImports.cshtml、_ViewStart.cshtml等基础文件(示例中为保持最简,页面将Layout显式置空);dotnet new web:生成最小化 Web 宿主项目,仅包含Program.cs;dotnet add ... reference ...:一次性为WebApplication.csproj添加对两个类库的ProjectReference,这是宿主应用能发现类库中页面的关键一步;dotnet new page -n Index -o Areas/Module1/Pages:在指定输出目录中创建 Razor Pages 的Index.cshtml与Index.cshtml.cs(PageModel)文件。-o参数决定了页面的物理路径,进而影响其 Area 归属与路由。
四、.csproj 关键配置:Razor SDK 与框架引用
RCL 之所以能承载并编译 Razor 内容,靠的是 .csproj 中的几处关键配置。仓库中两个类库的工程文件完全一致,以 RazorClassLibrary1.csproj 为例:
<Project Sdk="Microsoft.NET.Sdk.Razor">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<AddRazorSupportForMvc>true</AddRazorSupportForMvc>
<ImplicitUsings>true</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
</Project>
逐项解读:
Sdk="Microsoft.NET.Sdk.Razor":Razor 类库专用的项目 SDK,负责在编译时把.cshtml/.razor编译进程序集,并生成Microsoft.AspNetCore.Razor.Hosting.RazorCompiledItem元数据,使页面在运行时可以被宿主发现;<TargetFramework>net10.0</TargetFramework>:当前仓库示例统一面向 .NET 10。仓库根目录的 global.json 声明了 SDK 版本10.0.0(rollForward: major),因此运行本示例建议使用 .NET 10 SDK 及以上;<AddRazorSupportForMvc>true</AddRazorSupportForMvc>:开启对 MVC(含 Razor Pages 基础设施)的编译支持,使类库中的 Razor Pages / 视图可被 MVC 引擎发现;<ImplicitUsings>true</ImplicitUsings>:启用隐式using,简化源码中的命名空间引用;<FrameworkReference Include="Microsoft.AspNetCore.App" />:为类库添加对 ASP.NET Core 共享框架的引用,这是 RCL 能使用PageModel、Controller等框架类型的前提(与普通类库引用 NuGet 包的方式不同,这里以框架引用的形式接入)。
五、在类库中用 Razor Pages 组织 UI
5.1 页面文件与 PageModel
类库 1 的页面位于 Areas/Module1/Pages/Index.cshtml:
@page
@model Module1.Pages.IndexModel;
@{
Layout = null;
}
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width" />
<title>Razor class library 1</title>
</head>
<body>
<h1>Razor class library 1</h1>
<h2>Hello world from: RazorClassLibrary1/Areas/Module1/Pages/Index.cshml</h2>
</body>
</html>
对应的代码隐藏类 Index.cshtml.cs:
namespace Module1.Pages
{
public class IndexModel : PageModel
{
public void OnGet()
{
}
}
}
值得注意的细节:
@page指令声明这是一个 Razor Page,且未指定路由模板。结合 Area 的目录结构(Areas/Module1/Pages),Razor Pages 约定式路由会把它映射为/module1(Area 名小写化后的路径);@model Module1.Pages.IndexModel指定页面模型类型,命名空间Module1.Pages与物理目录Areas/Module1/Pages对应(由dotnet new page -o自动生成的命名空间即由此而来);Layout = null表示该页面不使用共享布局,直接输出完整 HTML——这是 Hello World 示例刻意保持"零依赖"的做法;- 类库 2 的页面结构完全对称,位于 Areas/Module2/Pages/Index.cshtml,路由对应
/module2。
5.2 为什么用 Areas 隔离
多个 RCL 各自独立地提供页面时,如果都放在根级 Pages 目录下,路由与命名空间极易冲突。把每个类库的页面放进独立的 Area(Module1、Module2),一方面让路由天然隔离(/module1、/module2),另一方面让模型类型名(Module1.Pages.IndexModel)互不干扰。这也是多模块、插件化 UI 架构中最常见的组织方式。
六、宿主 Web 应用如何接入类库页面
6.1 项目引用
宿主应用通过 ProjectReference 把两个类库拉入编译与运行时范围,见 WebApplication.csproj:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>true</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\RazorClassLibrary1\RazorClassLibrary1.csproj" />
<ProjectReference Include="..\RazorClassLibrary2\RazorClassLibrary2.csproj" />
</ItemGroup>
</Project>
只要宿主注册了 Razor Pages 服务并映射路由,类库中编译好的页面就会被自动纳入路由表——宿主应用无需为类库页面编写任何额外代码。
6.2 服务注册与路由映射
Program.cs 是整个接入逻辑的核心:
var builder = WebApplication.CreateBuilder();
builder.Services.AddRazorPages();
var app = builder.Build();
app.MapRazorPages();
app.Run(async (context) =>
{
context.Response.Headers.Append("Content-Type", "text/html");
await context.Response.WriteAsync(@"<html>
<body>
<h1>Hello World from the Web Application!</h1>
Visit page from <a href=""/module1"">RazorClassLibrary1</a> and <a href=""/module2"">RazorClassLibrary2</a>.
</body>
</html>");
});
app.Run();
关键调用链:
builder.Services.AddRazorPages():向依赖注入容器注册 Razor Pages 相关服务(RazorPagesOptions、页面编译与执行器等)。宿主会扫描所有已引用程序集中的 Razor 页面资产,包括类库中编译的页面;app.MapRazorPages():把 Razor Pages 的约定式路由(/module1、/module2)挂载到终结点路由表。注意这里使用的是MapRazorPages(.NET 6+ 的终结点路由风格写法),页面路由依然遵循Areas/{Area}/Pages的默认约定;app.Run(...)内联中间件:当请求不匹配任何已映射的页面路由时(例如访问根路径/),由这段兜底中间件返回一个简单的 HTML 首页,并给出指向/module1、/module2的导航链接。它通过context.Response.Headers.Append("Content-Type", "text/html")显式指定响应类型。
6.3 运行与验证
在仓库中找到 projects/mvc/razor-class-library/razor-class-library-1/src/WebApplication 目录,运行:
dotnet run
或启用热重载模式方便开发调试:
dotnet watch run
启动后分别访问:
http://localhost:5000/module1:展示 RazorClassLibrary1 提供的页面;http://localhost:5000/module2:展示 RazorClassLibrary2 提供的页面;http://localhost:5000/:由宿主应用的内联中间件输出导航首页。
由此可以直观验证:两个类库中的页面已被宿主应用完整集成,且通过 Area 隔离后互不干扰。
七、RCL 的进阶方向(同章节延伸示例)
razor-class-library-1 只是 RCL 的最小闭环。仓库中同章节还有两个进阶示例,可作为继续深入的方向:
7.1 携带静态资源(CSS / JS / 图片)
razor-class-library-with-static-files 展示了如何在 RCL 中附带 JavaScript、图片与 CSS。它的关键在于 RazorClassLibrary1.csproj 中把 wwwroot 下的资源作为嵌入资源打包:
<PropertyGroup>
<GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.FileProviders.Embedded" Version="10.0.11" />
</ItemGroup>
<ItemGroup>
<EmbeddedResource Include="wwwroot\**\*" />
<Content Update="**\*.cshtml" Pack="false" />
</ItemGroup>
宿主侧(Program.cs)通过 builder.Services.ConfigureOptions(typeof(RazorClassLibrary1.UiConfigureOptions)) 注册配置,利用 IPostConfigureOptions<StaticFileOptions> 将嵌入文件提供程序(ManifestEmbeddedFileProvider)合并进静态文件中间件的 CompositeFileProvider(实现见 BaseModuleUiConfigureOptions.cs)。页面侧则用 asp-append-version="true" 让 CSS/JS 链接带上版本指纹,并直接以 ~/img/xxx.png 形式引用嵌入图片。
7.2 在 RCL 中使用 Controller 与 View
razor-class-library-with-controllers 演示了 RCL 内使用 MVC 结构的做法。与 Razor Pages 不同,它把控制器放在 Areas/MyFeature/Controllers,视图放在 Areas/MyFeature/Views。控制器通过 <a href="https://link.gitcode.com/i/621653f0a7ec3ffc8019f430c6b6f55b" target="_blank">Area("MyFeature")] 声明区域归属(见 [HomeController.cs),AboutController 还演示了 <a href="https://link.gitcode.com/i/cc8bf2466ce5e5fd75faa023a2b87f3c" target="_blank">Route("[area]/about")] 的属性路由写法。宿主侧([Program.cs)需要注册 AddControllersWithViews(),并显式映射两条路由:
app.MapControllerRoute("areas", "{area}/{controller=Home}/{action=Index}/{id?}");
app.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
其中第一条带 {area} 段的路由,正是为了让类库中的 Area 控制器可被访问。
八、要点总结
- RCL 的价值:把 Razor 页面 / 视图 / 静态资源封装成独立程序集,跨项目复用,是多模块应用和组件化 UI 的基础设施;
- 三步接入:
dotnet new razorclasslib创建类库 → 在Areas/*/Pages下添加页面 → 宿主项目添加ProjectReference并调用AddRazorPages()+MapRazorPages(); - 关键配置:RCL 工程必须使用
Microsoft.NET.Sdk.Razor、FrameworkReference Include="Microsoft.AspNetCore.App",如需 MVC 支持还要设置<AddRazorSupportForMvc>true</AddRazorSupportForMvc>; - 路由隔离:借助 Area 约定(
Areas/{Area}/Pages)让多个类库的页面各归其位,避免路由与类型命名冲突; - 运行方式:在
src/WebApplication目录下执行dotnet run或dotnet watch run,访问/module1、/module2验证效果。
完整的可运行源码可参考仓库中的 razor-class-library-1/src 目录,进阶玩法可继续阅读 razor-class-library-with-static-files 与 razor-class-library-with-controllers 两个姊妹示例。