create-datadriven-aspnetcore

生成或搭建 ASP.NET Core 代码

生成 ASP.NET Core 搭建代码——控制器、视图、Razor Pages、Blazor 组件、Minimal API 终结点。生成的代码会匹配项目现有的 CSS 框架、布局约定和编码模式。不使用基于 CLI 的搭建/代码生成工具；仍需使用标准 dotnet CLI 命令进行生成、还原和迁移。

适用场景

• 为 ASP.NET Core 项目中的模型添加 CRUD 页面、视图或组件
• 使用 Entity Framework Core 搭建 API 控制器或 Minimal API 终结点
• 生成由 DbContext 支持的 Razor Pages、MVC 视图或 Blazor 组件

不适用场景

• 项目不是 ASP.NET Core 项目
• 需要搭建非 Web 产物（类库、控制台应用等）

输入

输入	必填	说明
搭建请求	是	用自然语言描述要搭建的内容（见下文格式）
项目文件路径	是	目标 .csproj 文件的完整路径
解决方案根目录路径	建议填写	多项目解决方案的解决方案根目录路径

搭建请求格式

搭建请求应使用自然语言描述要搭建的内容。请求必须包含目标项目路径和足够的详细信息，以便 Agent 生成正确的代码。示例：

使用 EF 的 Razor Pages：

Scaffold Razor Pages with CRUD for the `<ModelName>` model (from `<Namespace>`) in project `<path-to-csproj>`.
Create a new DbContext `<DbContextName>` using <database-provider>.
Also scaffold CRUD for any entity that `<ModelName>` depends on via required foreign keys, so parent entities can be created first.

Blazor CRUD 组件：

Scaffold Blazor CRUD components for the `<ModelName>` model (from `<Namespace>`) in project `<path-to-csproj>`.
Create a new DbContext `<DbContextName>` using <database-provider>.

Minimal API 终结点：

Scaffold Minimal API endpoints for the `<ModelName>` model (from `<Namespace>`) in project `<path-to-csproj>`.
Name the endpoints class `<EndpointsClassName>`.
Create a new DbContext `<DbContextName>` using <database-provider>.
Enable OpenAPI support.

带视图的 MVC 控制器：

Scaffold an MVC controller with views and Entity Framework for the `<ModelName>` model (from `<Namespace>`) in project `<path-to-csproj>`.
Name the controller `<ControllerName>`.
Use existing DbContext `<DbContextName>`.
Generate views.

空白项（不使用 EF）：

Scaffold an empty Razor Page named `<PageName>` in project `<path-to-csproj>`.

工作流

步骤 1：了解搭建请求

解析搭建请求，以确定：

• 搭建器类型：Razor Pages、Blazor 组件、MVC 控制器、Minimal API、空白页面/视图/组件
• 模型类及其命名空间
• DbContext：新建或现有，数据库提供程序（SQLite、SQL Server 等）
• 命名项：控制器名称、终结点类名称、页面名称、视图名称、区域名称
• 选项：OpenAPI、异步操作、分部视图、自定义布局
• 外键范围：是否还要为必需外键引用的父实体搭建 CRUD

执行检查清单

按顺序完成适用的检查清单。若必需的外键要求先创建父资源，请勿只创建所请求的子资源就停止。

所有 EF 脚手架

1. 编辑前检查项目文件、Program.cs、目标模型、验证特性、导航属性和外键。
2. 复用所请求的现有 DbContext；否则创建所请求的上下文。仅添加所需的提供程序包，并使用所请求的提供程序和连接字符串，通过 AddDbContext 注册它。需要迁移但缺少 Microsoft.EntityFrameworkCore.Design 时，必须添加该包（PrivateAssets="all"）。
3. 为所请求的实体及所有必需的父实体生成完整的 CRUD：列表、详情、创建、编辑和删除。
4. 使用 EF 迁移生命周期：创建迁移并应用。绝不要调用 EnsureCreated，也不要在 Program.cs 中为数据库添加种子数据。
5. 还原、构建并测试生成的项目。报告完成前修复所有错误。

MVC、Razor Pages 和 Blazor

1. 生成标记前，检查现有布局、CSS 和具有代表性的 UI。
2. 生成完整的子资源及必需的父资源 UI 流程，包括通往每个资源的导航路径，以便用户能在创建子资源前创建父资源。
3. 遵循现有的 UI 框架和惯例；保留 Blazor 现有的渲染模式配置。

Minimal APIs

1. 为每种资源使用一个路由组，并为子资源和必需的父资源映射 GET（列表和按 ID 获取）、POST、PUT 和 DELETE 端点。
2. 为每个端点添加 OpenAPI 元数据：唯一名称、标签、描述、成功/错误响应元数据；启用 OpenAPI 时还要添加 WithOpenApi。
3. 创建一个包含所有 CRUD 请求的可执行 .http 文件。先创建父记录，在子资源请求中记录或明确复用父记录返回的 ID，并按依赖顺序运行请求。

第 2 步：发现 UI 风格（仅适用于非 API 脚手架）

对于 API 控制器和 Minimal API 端点，请跳过此步骤。

1. 检查项目的布局文件（_Layout.cshtml、MainLayout.razor 或同等文件）
2. 检查主 CSS 文件（site.css、app.css、Tailwind 配置等）
3. 检查项目中 1–2 个现有页面、视图或组件

所有生成的文件都必须符合现有的 UI 框架、CSS 类和惯例。若使用 Bootstrap，请生成 Bootstrap 标记；若使用 Tailwind，请生成 Tailwind 标记。

第 3 步：应用 Blazor 特定规则（仅适用于 Blazor 脚手架）

对于非 Blazor 脚手架，请跳过此步骤。

• [SupplyParameterFromForm] 属性必须使用 = new()（而不是 null!）——这可防止 EditForm 在初始 GET 时崩溃
• Program.cs 必须在 AddRazorComponents() 上链接 .AddInteractiveServerComponents()，并在 MapRazorComponents<App>() 上链接 .AddInteractiveServerRenderMode()。只有在生成的组件实际使用 @rendermode InteractiveServer（或项目已有此配置）时，才添加交互式服务器服务/渲染模式。
• 不要替换现有的链式渲染模式调用（例如 .AddInteractiveWebAssemblyRenderMode()）

第 4 步：生成代码

手动生成所有代码文件。遵循以下限制：

• 不要使用任何脚手架 CLI 工具
• 不要添加超出脚手架功能所需的程序包（例如，不要添加 RuntimeCompilation 或其他便捷程序包）
• 遵循项目现有文件的编码风格（命名惯例、缩进、命名空间模式）

为 API 端点添加 OpenAPI 元数据（仅适用于 API 脚手架生成器）

启用 OpenAPI 支持并生成 Minimal API 或 MVC API 端点时，为每个端点添加丰富的元数据，让 OpenAPI 文档更具描述性和实用性：

• .WithName("GetTodoItems") — 为每个端点设置唯一的操作 ID
• .WithTags("TodoItems") — 按资源对端点分组
• .WithDescription("Returns all todo items") — 提供易于理解的说明
• .Produces<List<TodoItem>>(StatusCodes.Status200OK) — 记录成功响应类型
• .Produces(StatusCodes.Status404NotFound) — 记录错误响应
• .ProducesValidationProblem() — 用于验证输入的端点
• .WithOpenApi() — 将端点纳入 OpenAPI 生成（如果尚未全局启用）

Minimal API GET 端点示例：

group.MapGet("/", async (TodoDbContext db) =>
        await db.TodoItems.ToListAsync())
    .WithName("GetAllTodoItems")
    .WithTags("TodoItems")
    .WithDescription("Returns all todo items")
    .Produces<List<TodoItem>>(StatusCodes.Status200OK);

步骤 5：设置 Entity Framework（如适用）

如果脚手架生成请求不涉及 Entity Framework，请跳过此步骤。

• 切勿在 Program.cs 中填充数据库数据 — 始终使用迁移
• 对于 dotnet ef：优先使用本地工具清单中的 dotnet tool restore。仅在不存在工具清单时才全局安装
• 检查模型中的导航属性和外键。确保为被引用的实体创建了 CRUD 端点/页面
• 对于 API 脚手架生成器：.http 文件必须先创建父实体，再创建子实体。使用与创建顺序一致的外键值

步骤 6：生成 .http 文件（仅适用于 API 脚手架生成器）

非 API 脚手架生成器请跳过此步骤。

1. 在项目目录中创建名为 {ModelName}.http 的 .http 文件。如果已存在同名文件，则依次追加数字后缀（Product2.http、Product3.http），直到名称唯一
2. 为生成的每个 CRUD 端点添加示例请求，包括父实体/依赖实体的端点
3. 每个请求必须指向与实际映射端点相匹配的正确 URL 路径
4. 请求标签必须准确描述操作（例如，“创建类别”必须向 categories 端点发送 POST 请求）
5. 按依赖关系排列请求：先创建父实体，再创建子实体
6. 如果可能，使用 HTTP 客户端的变量/模板功能，从父实体创建响应中捕获 ID，并将其作为外键值用于子实体 POST 请求的负载中
7. 如果客户端无法捕获响应值，请添加注释，说明运行父实体创建请求后需要更新哪些外键 ID；执行请求时，不要留下与实际父记录不对应的不切实际的占位符值或假定外键值

步骤 7：验证

1. 在项目目录中运行 dotnet restore && dotnet build
2. 如果使用 Entity Framework，且这是首次验证：
   • 运行 dotnet ef migrations add InitialCreate
   • 运行 dotnet ef database update
   • 如果多次运行此步骤，必须将“InitialCreate”改为其他名称，因为 EF Core 要求迁移名称唯一。
3. 如果是 API 脚手架生成器：
   • 检查 Properties/launchSettings.json — 如果存在名为 https 的配置文件，则使用 dotnet run --launch-profile https
   • 按依赖顺序逐个执行所有 .http 请求
   • 报告每个请求的方法、URL 和状态码
   • 如果任何请求返回非 2xx 状态码，则停止并修复
4. 修复所有错误，直到构建成功且无错误

验证清单

• 所有生成的文件均符合项目现有的 CSS 框架和惯例
• dotnet build 成功，且无错误
• EF 迁移已成功应用（如适用）
• 所有 .http 请求均返回 2xx 状态码（如果是 API 脚手架生成器）
• 未添加任何禁止的包（RuntimeCompilation 等）
• 未调用任何 CLI 脚手架工具
• Blazor [SupplyParameterFromForm] 属性使用 = new()（如果是 Blazor 脚手架生成器）

常见问题

问题	解决方案
生成的 UI 与项目的 CSS 框架不匹配	生成代码前，务必先检查布局和 CSS 文件（步骤 2）
Blazor EditForm 在初始 GET 请求时崩溃	对于 [SupplyParameterFromForm] 属性，使用 = new()，而不是 null!
因缺少父实体的 CRUD 而导致 EF 迁移失败	如果请求提到外键，请为依赖外键的实体生成 CRUD
.http 文件中的外键值不正确	按依赖关系排列请求；使用与创建顺序一致的值
找不到 dotnet ef	先尝试运行 dotnet tool restore；仅在备用情况下全局安装
添加了不必要的包	仅添加脚手架生成功能明确要求的包
生成的代码使用了不同的命名约定	生成前检查现有项目文件，以匹配命名模式

参考资料

• Entity Framework Core DbContext 生命周期、配置和初始化
• ASP.NET Core 中的 OpenAPI 概述 — 特定于 .NET 10；其他版本也有类似页面