企业官网建设流程全解析

在 Web 开发领域，ASP.NET Core 以其高性能、跨平台和模块化设计，已成为构建现代 Web 应用的主流框架之一。对于需要快速开发、结构清晰且不涉及复杂 SPA 交互的页面型应用，Razor Pages 提供了一种比传统 MVC 模型更聚焦、更直观的开发模式。它简化了控制器和视图的分离，将处理特定页面的逻辑和视图紧密耦合在一个文件中，使得页面职责更明确，代码组织更符合直觉。本文将带你从零开始，使用 ASP.NET Core Razor Pages 构建一个具备基本 CRUD 功能的网站，涵盖从环境搭建、项目结构解析、页面创建、数据绑定、表单处理到部署准备的全过程。无论你是刚接触 ASP.NET Core 的开发者，还是希望从 MVC 转向更轻量级页面模型的开发者，都能通过本文获得一个可运行、可扩展的实践起点。

1. 理解 ASP.NET Core Razor Pages 的核心设计

在深入代码之前，理解 Razor Pages 的设计哲学至关重要。它并非 MVC 的替代品，而是在 MVC 框架之上，针对“页面”这一特定场景的优化抽象。

1.1 与 MVC 模式的对比

传统的 ASP.NET Core MVC 遵循“模型-视图-控制器”模式，一个用户请求通常需要经过路由匹配到控制器（Controller），控制器中的动作方法（Action）处理业务逻辑并选择视图（View）进行渲染。这种分离在大型、复杂应用中有利于职责划分，但对于一个简单的“关于我们”或“联系我们”页面，创建独立的控制器和视图文件可能显得繁琐。

Razor Pages 将关注点从“控制器动作”转移到“页面”本身。每个 Razor 页面（.cshtml文件）通常对应一个物理文件路径，并且拥有一个与之关联的 Page Model 类（.cshtml.cs文件）。这个 Page Model 类包含了处理该页面 HTTP 请求（如 GET, POST）的处理程序方法，以及页面所需的数据和逻辑。这种设计使得与特定页面相关的所有代码都集中在一起，降低了认知负担，尤其适合内容导向或表单提交类的页面。

1.2 Razor Pages 的核心组件

一个典型的 Razor Page 项目包含以下核心部分：

• 页面文件（.cshtml）：使用 Razor 语法混合 HTML 和 C# 代码的视图模板。它默认继承自对应的 Page Model 类。
• Page Model 类（.cshtml.cs）：页面的后台代码类，继承自PageModel。它包含：
  • 属性：用于在页面和模型之间双向绑定的数据。
  • 处理程序方法：如OnGet()、OnPost()、OnPostAsync()等，响应特定的 HTTP 动词。
  • 辅助方法：页面相关的业务逻辑。
• @page指令：位于.cshtml文件顶部的指令（如@page），它是将文件标记为 Razor Page 的关键，并可以定义路由模板（如@page "{id:int}"）。
• 布局（_Layout.cshtml）和视图起始页（_ViewStart.cshtml）：用于定义网站的统一布局和默认视图配置，与 MVC 中的概念一致。
• 依赖注入（DI）：ASP.NET Core 内置的 DI 容器，可以方便地将服务（如数据库上下文、日志器）注入到 Page Model 的构造函数中。

这种结构使得开发一个功能页面的流程变得非常线性：创建页面 -> 在 Page Model 中定义数据属性和处理程序 -> 在 Razor 视图中绑定和渲染数据。

2. 环境准备与项目创建

在开始编码前，需要确保开发环境就绪。我们将使用当前最新的长期支持（LTS）版本进行演示，其稳定性和社区支持都较好。

2.1 开发环境与工具

• .NET SDK：确保安装了 .NET 8.0 SDK 或更高版本。你可以通过命令行dotnet --info来验证。
• 集成开发环境（IDE）：
  • Visual Studio 2022（社区版免费）：对 ASP.NET Core 开发提供最全面的支持，包括项目模板、调试和发布工具。
  • Visual Studio Code：轻量级且跨平台，需安装 C# 扩展。
• 数据库（可选）：为了演示数据持久化，我们将使用 SQL Server LocalDB（Visual Studio 自带）或 SQLite。你也可以使用其他 EF Core 支持的数据库。

2.2 创建新的 Razor Pages 项目

使用命令行或 IDE 创建项目是最直接的方式。

通过 .NET CLI 创建：打开终端，导航到你的工作目录，运行以下命令：

dotnet new webapp -n RazorPagesDemo -o RazorPagesDemo cd RazorPagesDemo

此命令使用webapp模板创建了一个名为RazorPagesDemo的 Razor Pages 项目。

• -n指定项目名称。
• -o指定输出目录。

通过 Visual Studio 创建：

1. 启动 Visual Studio，选择“创建新项目”。
2. 搜索并选择“ASP.NET Core Web 应用”模板，点击“下一步”。
3. 输入项目名称（如RazorPagesDemo）和位置，点击“下一步”。
4. 在“其他信息”对话框中，确保“框架”选择.NET 8.0 (长期支持)，“身份验证类型”选择“无”，并勾选“不使用顶级语句”（可选，根据编码习惯）。点击“创建”。

创建完成后，使用dotnet run命令或在 IDE 中按 F5 运行项目。默认会在浏览器中打开https://localhost:5001或http://localhost:5000，显示一个预制的欢迎页面，这证明基础项目已成功运行。

2.3 初始项目结构解析

创建的项目包含以下关键目录和文件：

RazorPagesDemo/ ├── Pages/ # Razor Pages 的核心目录 │ ├── Index.cshtml # 主页对应的 Razor Page │ ├── Index.cshtml.cs # 主页的 Page Model │ ├── Privacy.cshtml # 隐私页面 │ ├── Shared/ # 共享视图组件 │ │ ├── _Layout.cshtml # 主布局文件 │ │ └── _ValidationScriptsPartial.cshtml # 客户端验证脚本 │ └── _ViewImports.cshtml # 全局导入命名空间 │ └── _ViewStart.cshtml # 设置所有页面的默认布局 ├── appsettings.json # 应用配置（如连接字符串） ├── Program.cs # 应用启动和服务的配置入口 └── RazorPagesDemo.csproj # 项目文件

Program.cs是应用的入口，负责配置服务（Service）和请求处理管道（Middleware Pipeline）。这是理解 ASP.NET Core 启动过程的关键。

3. 构建一个完整的 CRUD 功能页面

我们将创建一个简单的“产品管理”页面，实现产品的列表展示、创建、编辑和删除功能。这将涉及模型定义、数据访问、页面创建和表单处理。

3.1 定义数据模型与数据库上下文

首先，在项目根目录创建一个Models文件夹，并在其中添加Product.cs类，代表产品实体。

// Models/Product.cs namespace RazorPagesDemo.Models; public class Product { public int Id { get; set; } // 主键 public string Name { get; set; } = string.Empty; public string Description { get; set; } = string.Empty; public decimal Price { get; set; } public DateTime CreatedDate { get; set; } = DateTime.Now; }

接下来，使用 Entity Framework Core（EF Core）来操作数据库。首先，添加必要的 NuGet 包。可以通过包管理器控制台或编辑.csproj文件实现。

通过 .NET CLI 添加包：

dotnet add package Microsoft.EntityFrameworkCore.SqlServer dotnet add package Microsoft.EntityFrameworkCore.Tools

如果使用 SQLite，则添加Microsoft.EntityFrameworkCore.Sqlite。

然后，创建数据库上下文类ApplicationDbContext.cs，通常也放在Models文件夹或新建的Data文件夹中。

// Data/ApplicationDbContext.cs using Microsoft.EntityFrameworkCore; using RazorPagesDemo.Models; namespace RazorPagesDemo.Data; public class ApplicationDbContext : DbContext { public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) : base(options) { } public DbSet<Product> Products => Set<Product>(); }

3.2 配置依赖注入与数据库连接

在Program.cs文件中，我们需要注册ApplicationDbContext到依赖注入容器，并配置数据库连接。

// Program.cs using Microsoft.EntityFrameworkCore; using RazorPagesDemo.Data; var builder = WebApplication.CreateBuilder(args); // 添加服务到容器 builder.Services.AddRazorPages(); // 配置 DbContext，使用 SQL Server LocalDB builder.Services.AddDbContext<ApplicationDbContext>(options => options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection"))); // 如果使用 SQLite // builder.Services.AddDbContext<ApplicationDbContext>(options => // options.UseSqlite(builder.Configuration.GetConnectionString("DefaultConnection"))); var app = builder.Build(); // ... 后续的中间件配置保持不变

在appsettings.json中配置连接字符串：

{ "ConnectionStrings": { "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=RazorPagesDemoDb;Trusted_Connection=True;MultipleActiveResultSets=true" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }

3.3 创建 Razor Page 实现 CRUD

我们将为产品管理创建一组页面。通常，我们会将相关页面放在一个子文件夹下，例如Pages/Products。

3.3.1 创建列表/索引页（Index）

在Pages文件夹下新建Products文件夹。右键点击Products文件夹，选择“添加” -> “Razor 页面”。在对话框中，选择“Razor 页面 - 空”，命名为Index.cshtml。这将同时生成Index.cshtml和Index.cshtml.cs。

首先，编辑 Page Model 文件Index.cshtml.cs：

// Pages/Products/Index.cshtml.cs using Microsoft.AspNetCore.Mvc.RazorPages; using Microsoft.EntityFrameworkCore; using RazorPagesDemo.Data; using RazorPagesDemo.Models; namespace RazorPagesDemo.Pages.Products; public class IndexModel : PageModel { private readonly ApplicationDbContext _context; public IndexModel(ApplicationDbContext context) { _context = context; // 通过构造函数注入 DbContext } public IList<Product> ProductList { get; set; } = default!; // 用于在页面上显示的产品列表 public async Task OnGetAsync() // 处理页面的 GET 请求 { // 从数据库异步获取所有产品，按创建日期倒序排列 ProductList = await _context.Products.OrderByDescending(p => p.CreatedDate).ToListAsync(); } }

然后，编辑 Razor 视图文件Index.cshtml：

@page @model RazorPagesDemo.Pages.Products.IndexModel @{ ViewData["Title"] = "产品列表"; } <h1>产品管理</h1> <p> <a asp-page="Create" class="btn btn-primary">创建新产品</a> </p> <table class="table"> <thead> <tr> <th>@Html.DisplayNameFor(model => model.ProductList[0].Name)</th> <th>@Html.DisplayNameFor(model => model.ProductList[0].Description)</th> <th>@Html.DisplayNameFor(model => model.ProductList[0].Price)</th> <th>@Html.DisplayNameFor(model => model.ProductList[0].CreatedDate)</th> <th>操作</th> </tr> </thead> <tbody> @foreach (var item in Model.ProductList) { <tr> <td>@Html.DisplayFor(modelItem => item.Name)</td> <td>@Html.DisplayFor(modelItem => item.Description)</td> <td>@Html.DisplayFor(modelItem => item.Price)</td> <td>@Html.DisplayFor(modelItem => item.CreatedDate)</td> <td> <a asp-page="./Edit" asp-route-id="@item.Id" class="btn btn-sm btn-warning">编辑</a> <a asp-page="./Details" asp-route-id="@item.Id" class="btn btn-sm btn-info">详情</a> <a asp-page="./Delete" asp-route-id="@item.Id" class="btn btn-sm btn-danger">删除</a> </td> </tr> } </tbody> </table>

• @page指令将其标记为 Razor Page。
• @model指令指定了该页面使用的 Page Model 类型。
• asp-page和asp-route-id是 Tag Helper，用于生成指向其他 Razor Page 的正确链接。
• Html.DisplayNameFor和Html.DisplayFor也是 Tag Helper，用于安全地显示模型属性的名称和值。

3.3.2 创建新增页（Create）

同样在Pages/Products文件夹下，添加一个新的 Razor 页面，命名为Create.cshtml。

首先，编辑 Page Model 文件Create.cshtml.cs：

// Pages/Products/Create.cshtml.cs using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.RazorPages; using RazorPagesDemo.Data; using RazorPagesDemo.Models; namespace RazorPagesDemo.Pages.Products; public class CreateModel : PageModel { private readonly ApplicationDbContext _context; public CreateModel(ApplicationDbContext context) { _context = context; } [BindProperty] // 此属性将与表单数据进行双向绑定 public Product Product { get; set; } = default!; public IActionResult OnGet() // GET 请求时，仅返回页面 { return Page(); } public async Task<IActionResult> OnPostAsync() // POST 请求时，处理表单提交 { // 检查模型状态是否有效（基于数据注解验证） if (!ModelState.IsValid) { return Page(); // 验证失败，返回当前页面并显示错误信息 } // 将新产品添加到数据库 _context.Products.Add(Product); await _context.SaveChangesAsync(); // 成功后重定向到列表页 return RedirectToPage("./Index"); } }

然后，编辑 Razor 视图文件Create.cshtml：

@page @model RazorPagesDemo.Pages.Products.CreateModel @{ ViewData["Title"] = "创建产品"; } <h1>创建新产品</h1> <hr /> <div class="row"> <div class="col-md-4"> <form method="post"> <div asp-validation-summary="ModelOnly" class="text-danger"></div> <div class="form-group"> <label asp-for="Product.Name" class="control-label"></label> <input asp-for="Product.Name" class="form-control" /> <span asp-validation-for="Product.Name" class="text-danger"></span> </div> <div class="form-group"> <label asp-for="Product.Description" class="control-label"></label> <textarea asp-for="Product.Description" class="form-control"></textarea> <span asp-validation-for="Product.Description" class="text-danger"></span> </div> <div class="form-group"> <label asp-for="Product.Price" class="control-label"></label> <input asp-for="Product.Price" class="form-control" /> <span asp-validation-for="Product.Price" class="text-danger"></span> </div> <div class="form-group mt-3"> <input type="submit" value="创建" class="btn btn-primary" /> <a asp-page="Index" class="btn btn-secondary">返回列表</a> </div> </form> </div> </div> @section Scripts { @{await Html.RenderPartialAsync("_ValidationScriptsPartial");} }

• form method="post"表示表单提交时将触发 Page Model 中的OnPostAsync方法。
• asp-forTag Helper 将 HTML 输入元素与 Page Model 中的Product属性绑定。
• asp-validation-for和asp-validation-summary用于显示服务端验证错误信息。
• @section Scripts引入了客户端验证所需的 jQuery 验证脚本（由_ValidationScriptsPartial提供）。

3.3.3 应用数据迁移并更新数据库

在创建了模型和上下文后，需要使用 EF Core 迁移来创建或更新数据库架构。

打开终端（在项目目录下）或 Visual Studio 的包管理器控制台，执行以下命令：

dotnet ef migrations add InitialCreate dotnet ef database update

• migrations add会基于你的DbContext和模型类生成迁移代码文件。
• database update会将迁移应用到数据库，如果数据库不存在则会创建它。

3.4 运行与验证

现在，运行应用 (dotnet run或 F5)。在浏览器中导航到/Products（完整 URL 如https://localhost:5001/Products）。你应该能看到产品列表页面（初始为空）。点击“创建新产品”，填写表单并提交。成功后，页面将重定向到列表页，并显示新创建的产品。你可以继续测试编辑和删除功能（需要按类似模式创建Edit.cshtml和Delete.cshtml页面）。

4. 关键机制与高级特性详解

完成基础 CRUD 后，需要理解背后的一些关键机制，这能帮助你在遇到问题时进行排查，并实现更复杂的功能。

4.1 路由与@page指令

Razor Pages 的路由默认基于文件系统。Pages/Index.cshtml对应根路径/，Pages/Products/Index.cshtml对应/Products，Pages/Products/Create.cshtml对应/Products/Create。

你可以通过@page指令自定义路由。例如，在Pages/Products/Details.cshtml顶部添加：

@page "{id:int}"

这定义了一个路由模板，要求 URL 中必须包含一个名为id的整数参数，例如/Products/Details/5。在对应的 Page Model 中，你可以添加一个名为id的参数到OnGet方法中来接收它：

public async Task<IActionResult> OnGetAsync(int? id) { if (id == null) { return NotFound(); } // ... 根据 id 查询产品 }

4.2 模型绑定与验证

在上面的Create页面中，我们使用了[BindProperty]特性。这表示在 HTTP POST 请求中，表单数据会自动绑定到Product属性上。模型绑定器会尝试将表单字段的名称（如Product.Name）与模型属性的名称进行匹配。

数据验证通过数据注解（Data Annotations）实现。修改Product.cs模型类：

using System.ComponentModel.DataAnnotations; namespace RazorPagesDemo.Models; public class Product { public int Id { get; set; } [Required(ErrorMessage = "产品名称是必填项")] [StringLength(100, ErrorMessage = "名称长度不能超过100个字符")] [Display(Name = "产品名称")] public string Name { get; set; } = string.Empty; [Display(Name = "描述")] public string Description { get; set; } = string.Empty; [Required] [Range(0.01, 10000, ErrorMessage = "价格必须在0.01到10000之间")] [DataType(DataType.Currency)] [Display(Name = "价格")] public decimal Price { get; set; } [Display(Name = "创建时间")] [DataType(DataType.DateTime)] public DateTime CreatedDate { get; set; } = DateTime.Now; }

添加注解后，在Create或Edit页面提交表单时，ModelState.IsValid会自动检查这些规则。客户端验证（由_ValidationScriptsPartial引入）也会在浏览器端进行即时校验。

4.3 处理程序方法命名约定

Razor Pages 通过处理程序方法名来响应不同的 HTTP 动词和操作。常见命名模式有：

• OnGet/OnGetAsync：响应 HTTP GET 请求，用于初始化页面。
• OnPost/OnPostAsync：响应 HTTP POST 请求，通常用于处理表单提交。
• OnPost{HandlerName}：例如OnPostDeleteAsync。当表单中有名为handler的字段（<input type="hidden" name="handler" value="Delete" />）或其提交按钮的asp-page-handler属性设置为Delete时，会调用此方法。这允许一个页面处理多个 POST 操作。

4.4 部分视图与视图组件

对于可重用的 UI 片段，可以使用部分视图（Partial View）。例如，创建一个_ProductSummary.cshtml放在Pages/Shared/或Pages/Products/下：

@model Product <div class="card"> <div class="card-body"> <h5 class="card-title">@Model.Name</h5> <p class="card-text">@Model.Description</p> <p class="card-text"><strong>价格：</strong>@Model.Price.ToString("C")</p> </div> </div>

在Index.cshtml中，可以使用以下方式渲染：

@foreach (var item in Model.ProductList) { <partial name="_ProductSummary" model="item" /> }

对于更复杂、包含逻辑的 UI 组件，可以考虑使用视图组件（View Component）。

5. 常见问题排查与调试

在开发过程中，你可能会遇到以下典型问题。

5.1 页面 404 错误

5.2 模型绑定失败或验证错误

5.3 数据库操作问题

5.4 调试技巧

1. 使用日志：在Program.cs中配置日志级别，在 Page Model 或服务中注入ILogger<T>记录关键信息。
2. 浏览器开发者工具：利用“网络”选项卡查看请求/响应详情、状态码和表单数据；利用“控制台”查看 JavaScript 错误。
3. 设置断点：在 Visual Studio 或 VS Code 中，在 Page Model 的处理程序方法中设置断点，逐步执行以观察变量状态和程序流程。
4. 检查中间件顺序：在Program.cs的请求管道中，中间件的顺序很重要（如异常处理、静态文件、路由、认证授权）。确保UseRouting()和UseEndpoints()的顺序正确。

6. 生产环境部署与优化建议

将学习项目推向生产环境，需要考虑更多因素。

6.1 部署准备

1. 发布项目：使用dotnet publish -c Release -o ./publish命令发布项目到指定文件夹。-c Release表示使用发布配置进行优化。
2. 环境配置：生产环境的连接字符串、API 密钥等敏感信息不应硬编码在appsettings.json中。应使用环境变量、Azure Key Vault 或安全的配置源。在Program.cs中，环境变量会覆盖appsettings.json中的值。
3. 数据库迁移：生产环境通常不会直接运行dotnet ef database update。可以考虑：
   • 在 CI/CD 管道中生成 SQL 脚本 (dotnet ef migrations script)，由 DBA 审核后执行。
   • 在应用启动时自动迁移（需谨慎）：在Program.cs的app.Run()前添加using (var scope = app.Services.CreateScope()) { scope.ServiceProvider.GetRequiredService<ApplicationDbContext>().Database.Migrate(); }。

6.2 安全加固

1. 防跨站请求伪造（CSRF）：Razor Pages 默认启用了防伪令牌验证。确保表单中使用了@Html.AntiForgeryToken()或 Form Tag Helper（会自动添加令牌）。在 Page Model 的 POST 方法上使用[ValidateAntiForgeryToken]特性。
2. 输入验证：始终使用数据注解进行服务端验证。对于复杂逻辑，可以在 Page Model 中自定义验证逻辑并手动向ModelState添加错误。
3. SQL 注入防护：使用 EF Core 的参数化查询可以有效防止 SQL 注入。绝对不要使用字符串拼接来构造 SQL 语句。
4. HTTPS 重定向：在生产环境中，应强制使用 HTTPS。在Program.cs中，确保app.UseHttpsRedirection()中间件被启用。

6.3 性能与可维护性

1. 异步编程：所有涉及 I/O 操作（如数据库查询、文件读写、网络请求）的方法，都应使用异步模式（async/await），以提高应用的吞吐量和响应能力。
2. 分页查询：对于列表页，当数据量很大时，务必实现分页。可以使用Skip()和Take()方法，或 EF Core 的PaginatedList辅助类。
3. 依赖注入：将业务逻辑抽象到独立的服务类中，并通过构造函数注入到 Page Model。这提高了代码的可测试性和可维护性。
4. 客户端资源优化：使用 Bundler & Minifier 等工具压缩和合并 CSS、JavaScript 文件。考虑使用 CDN 加载常见的库（如 jQuery、Bootstrap）。

从简单的页面构建到包含数据访问、验证和基本安全措施的 CRUD 应用，Razor Pages 提供了一条清晰高效的开发路径。它的优势在于将关注点集中在“页面”这个逻辑单元上，减少了 MVC 中控制器和视图之间的间接层。对于管理后台、内容展示站、内部工具等页面导向型应用，这是一个非常值得考虑的架构选择。下一步，你可以探索更复杂的场景，如文件上传、身份认证与授权（使用 ASP.NET Core Identity）、实时通信（SignalR）或将其作为更大型应用中的一部分，与 Web API 协同工作。