Razor 类库(Razor Class Library)Hello World 实战:在 ASP.NET Core 中构建可复用的 UI 组件库

原创2026-10-14 20:02:342,246 阅读
文章标签:示例工程

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.Razor SDK,默认已含 _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();

关键调用链:

  1. builder.Services.AddRazorPages():向依赖注入容器注册 Razor Pages 相关服务(RazorPagesOptions、页面编译与执行器等)。宿主会扫描所有已引用程序集中的 Razor 页面资产,包括类库中编译的页面;
  2. app.MapRazorPages():把 Razor Pages 的约定式路由(/module1、/module2)挂载到终结点路由表。注意这里使用的是 MapRazorPages(.NET 6+ 的终结点路由风格写法),页面路由依然遵循 Areas/{Area}/Pages 的默认约定;
  3. 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 两个姊妹示例。

登录后查看全文
practical-aspnetcore