工程模板

January 28, 2026 · View on GitHub

简介

本项目是一个基于dotnet new的模板项目，用于快速创建一个基于 netcorepal-cloud-framework 的项目。

项目支持linux、windows、macOS平台。

前提条件

安装.NET 10 SDK（必需）。根据创建项目时选择的目标框架版本（--Framework 参数），您可能还需要安装对应的 SDK 版本：
- 使用 --Framework net8.0 时：需要安装 .NET 8.0 SDK
- 使用 --Framework net9.0 时：需要安装 .NET 9.0 SDK
- 使用 --Framework net10.0 时：仅需 .NET 10 SDK（默认）
SDK下载地址： https://dot.net/download
拥有Docker环境，用于自动化单元测试和集成测试。

推荐工具：
- Docker Desktop： https://www.docker.com/products/docker-desktop/
- Rancher Desktop： https://github.com/rancher-sandbox/rancher-desktop
- OrbStack： https://orbstack.dev/download
如果使用 Aspire（使用 --UseAspire 参数创建项目时），需要配置 Aspire 环境。请按以下步骤操作：

步骤 1：安装 Aspire SDK

访问 Aspire CLI 安装指南按照官方文档安装 Aspire SDK。

步骤 2：更新工作负载
```
dotnet workload update
```
步骤 3：信任 HTTPS 开发证书
```
dotnet dev-certs https --trust
```

如何使用

安装模板

dotnet new install NetCorePal.Template

安装Preview版本

dotnet new install NetCorePal.Template::<package-version>"

# 例如
dotnet new install NetCorePal.Template::3.1.0

安装Nightly版本

dotnet new install NetCorePal.Template::<package-version> --add-source "https://www.myget.org/F/netcorepal/api/v3/index.json"

创建项目

dotnet new netcorepal-web -n My.Project.Name

命令参数说明

模板支持多个参数来定制生成的项目，您可以根据需要选择不同的技术栈：

基本语法

dotnet new netcorepal-web -n <项目名称> [参数选项]

获取帮助

# 查看所有可用的参数和选项
dotnet new netcorepal-web --help

# 查看所有已安装的模板
dotnet new list

可用参数

参数	短参数	说明	可选值	默认值
`--Framework`	`-F`	目标 .NET 框架版本	`net8.0`, `net9.0`, `net10.0`	`net10.0`
`--Database`	`-D`	数据库提供程序	`MySql`, `SqlServer`, `PostgreSQL`, `Sqlite`, `GaussDB`, `DMDB`, `MongoDB`	`MySql`
`--MessageQueue`	`-M`	消息队列提供程序	`RabbitMQ`, `Kafka`, `AzureServiceBus`, `AmazonSQS`, `NATS`, `RedisStreams`, `Pulsar`	`RabbitMQ`
`--UseAspire`	`-U`	启用 Aspire Dashboard 支持	`true`, `false`	`false`
`--IncludeCopilotInstructions`	`-I`	是否包含 Copilot 指令文件	`true`, `false`	`true`
`--UseAdmin`		是否包含 Admin 功能（用户、角色、部门管理、权限系统、前端）	`true`, `false`	`false`

使用示例

# 使用默认配置（.NET 10.0 + MySQL + RabbitMQ）
dotnet new netcorepal-web -n My.Project.Name

# 使用 .NET 8.0 框架
dotnet new netcorepal-web -n My.Project.Name --Framework net8.0
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -F net8.0

# 使用 SQL Server 数据库
dotnet new netcorepal-web -n My.Project.Name --Database SqlServer
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -D SqlServer

# 使用 PostgreSQL 数据库
dotnet new netcorepal-web -n My.Project.Name --Database PostgreSQL

# 使用 SQLite 数据库（轻量级文件数据库，适合开发和测试）
dotnet new netcorepal-web -n My.Project.Name --Database Sqlite
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -D Sqlite

# 使用 MongoDB 数据库（NoSQL 文档数据库）
dotnet new netcorepal-web -n My.Project.Name --Database MongoDB
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -D MongoDB

# 使用 Kafka 消息队列
dotnet new netcorepal-web -n My.Project.Name --MessageQueue Kafka
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -M Kafka

# 组合使用多个参数（推荐使用短参数）
dotnet new netcorepal-web -n My.Project.Name -F net8.0 -D PostgreSQL -M Kafka

# 使用云服务（Azure Service Bus）
dotnet new netcorepal-web -n My.Project.Name -M AzureServiceBus

# 使用 Redis Streams 作为消息队列
dotnet new netcorepal-web -n My.Project.Name -M RedisStreams

# 启用 Aspire Dashboard 支持（用于可观测性和编排）
dotnet new netcorepal-web -n My.Project.Name --UseAspire
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -U

# 组合使用 Aspire 与其他选项
dotnet new netcorepal-web -n My.Project.Name -F net9.0 -D PostgreSQL -U

# 排除 Copilot 指令文件（不包含 .github 目录中的 copilot-instructions）
dotnet new netcorepal-web -n My.Project.Name --IncludeCopilotInstructions false
# 或使用短参数
dotnet new netcorepal-web -n My.Project.Name -I false

提示： 创建项目后，请根据选择的数据库和消息队列配置，使用对应的基础设施初始化脚本来启动所需的服务。详细说明请参考生成项目中的 scripts/README.md 文件。

关于 Admin 功能

当启用 --UseAdmin 选项时，模板会包含以下功能：

用户管理：用户的创建、更新、删除、查询等功能
角色管理：角色的创建、更新、删除、权限分配等功能
部门管理：部门的创建、更新、删除、树形结构管理等功能
权限系统：基于角色的权限控制（RBAC），支持权限码定义和验证
JWT 认证：完整的 JWT Token 认证和刷新 Token 机制
前端界面：基于 Vue 3 + Vben Admin 的管理后台界面

启用 Admin 功能后，系统会自动创建默认的管理员账户（用户名：admin，密码：123456）。

关于 Aspire Dashboard

当启用 --UseAspire 选项时，模板会生成以下额外的项目：

AppHost 项目：用于应用程序的编排和启动，集成了 Aspire Dashboard
ServiceDefaults 项目：包含共享的服务配置，如 OpenTelemetry、服务发现、健康检查等

启用 Aspire Dashboard 后，可以通过运行 AppHost 项目来启动应用程序并访问 Dashboard：

cd src/My.Project.Name.AppHost
dotnet run

Aspire Dashboard 提供了以下功能：

分布式追踪：可视化查看请求在不同服务间的流转
指标监控：实时监控应用程序的性能指标
日志聚合：集中查看所有服务的日志
服务健康检查：监控各服务的健康状态
资源管理：查看和管理应用程序使用的资源

进入项目目录

cd My.Project.Name

构建项目

dotnet build

运行测试

dotnet test

本地开发

如果您需要基于源码开发或调试本模板，可以按以下步骤操作：

克隆仓库

git clone https://github.com/netcorepal/netcorepal-cloud-template.git
cd netcorepal-cloud-template

从本地源码安装模板

方式一：直接从源码目录安装（推荐）

dotnet new install 支持直接从包含模板的源码目录安装，无需构建和打包：

# 建议先清理旧文件以避免冲突
git clean -fdX

# 在项目根目录直接安装（推荐）
dotnet new install . --force

--force 参数可以强制安装或更新模板，无需先卸载旧版本。这种方式最简单快捷，特别适合本地开发和调试。

修改模板文件后，重新运行安装命令即可更新：

# 修改模板文件后，直接重新安装
dotnet new install . --force

方式二：从构建的包安装

如果需要测试完整的打包流程，可以先构建再安装：

# 恢复依赖
dotnet restore

# 构建项目
dotnet build

# 打包模板
dotnet pack

# 从生成的 nupkg 文件安装
dotnet new install ./bin/Debug/NetCorePal.Template.1.0.0.nupkg

# 或者使用通配符安装
dotnet new install ./bin/Debug/*.nupkg

测试本地模板

安装后，您可以像使用正式版本一样创建项目来测试模板：

# 使用本地安装的模板创建项目
dotnet new netcorepal-web -n TestProject

# 进入测试项目目录
cd TestProject

# 构建和测试
dotnet build
dotnet test

查看已安装的模板

# 列出所有已安装的模板
dotnet new list

# 查看模板详细信息
dotnet new netcorepal-web --help

其它命令

更新模板

dotnet new update

dotnet new install NetCorePal.Template::<VERSION>

卸载模板

dotnet new uninstall NetCorePal.Template

IDE 代码片段配置

本模板提供了丰富的代码片段，帮助您快速生成常用的代码结构。

代码片段演示

Visual Studio 配置

运行以下 PowerShell 命令自动安装代码片段：

cd vs-snippets
.\Install-VSSnippets.ps1

或者手动安装：

打开 Visual Studio
转到 工具 > 代码片段管理器
导入 vs-snippets/NetCorePalTemplates.snippet 文件

VS Code 配置

VS Code 的代码片段已预配置在 .vscode/csharp.code-snippets 文件中，打开项目时自动生效。

JetBrains Rider 配置

Rider 用户可以直接使用 ABC.Template.sln.DotSettings 文件中的 Live Templates 配置。

可用的代码片段

NetCorePal (ncp) 快捷键

快捷键	描述	生成内容
`ncpcmd`	NetCorePal 命令	ICommand 实现(含验证器和处理器)
`ncpcmdres`	命令(含返回值)	ICommand<Response> 实现
`ncpar`	聚合根	Entity<Id> 和 IAggregateRoot
`ncprepo`	NetCorePal 仓储	IRepository 接口和实现
`ncpie`	集成事件	IntegrationEvent 和处理器
`ncpdeh`	域事件处理器	IDomainEventHandler 实现
`ncpiec`	集成事件转换器	IIntegrationEventConverter
`ncpde`	域事件	IDomainEvent 记录

Endpoint (ep) 快捷键

快捷键	描述	生成内容
`epp`	FastEndpoint(NCP风格)	完整的垂直切片实现
`epreq`	仅请求端点	Endpoint<Request>
`epres`	仅响应端点	EndpointWithoutRequest<Response>
`epdto`	端点 DTOs	Request 和 Response 类
`epval`	端点验证器	Validator<Request>
`epmap`	端点映射器	Mapper<Request, Response, Entity>
`epfull`	完整端点切片	带映射器的完整实现
`epsum`	端点摘要	Summary<Endpoint, Request>
`epnoreq`	无请求端点	EndpointWithoutRequest
`epreqres`	请求响应端点	Endpoint<Request, Response>
`epdat`	端点数据	静态数据类

代码分析可视化

框架提供了强大的代码流分析和可视化功能，帮助开发者直观地理解DDD架构中的组件关系和数据流向。

🎯 核心特性

自动代码分析：通过源生成器自动分析代码结构，识别控制器、命令、聚合根、事件等组件
多种图表类型：支持架构流程图、命令链路图、事件流程图、类图等多种可视化图表
交互式HTML可视化：生成完整的交互式HTML页面，内置导航和图表预览功能
一键在线编辑：集成"View in Mermaid Live"按钮，支持一键跳转到在线编辑器

🚀 快速开始

安装命令行工具来生成独立的HTML文件：

# 安装全局工具
dotnet tool install -g NetCorePal.Extensions.CodeAnalysis.Tools

# 进入项目目录并生成可视化文件
cd My.Project.Name/src/My.Project.Name.Web
netcorepal-codeanalysis generate --output architecture.html

✨ 主要功能

交互式HTML页面：
- 左侧树形导航，支持不同图表类型切换
- 内置Mermaid.js实时渲染
- 响应式设计，适配不同设备
- 专业的现代化界面
一键在线编辑：
- 每个图表右上角的"View in Mermaid Live"按钮
- 智能压缩算法优化URL长度
- 自动跳转到Mermaid Live Editor
- 支持在线编辑、导出图片、生成分享链接

📖 详细文档

完整的使用说明和示例请参考：

支持特性

文件存储
- 本地文件
- 阿里云对象存储
配置管理
- 文件配置（json、ini、yaml）
- Kubernetes ConfigMap
- Nacos
- Apollo
- AgileConfig
数据库
- SqlServer
- MySql
- PostgreSQL
- Sqlite
- GaussDB
- DMDB
- MongoDB
消息队列
- RabbitMQ
- Kafka
- NATS
- RedisStreams
- AzureServiceBus
- AmazonSQS
- Pulsar
服务注册发现
- Kubernetes
- Etcd
- Consul
- Zookeeper
- Eureka
- Nacos
API工具链
- Swagger
远程调用
- gRPC
- HttpClient
实时通讯
- SignalR
- WebSocket
缓存中间件
- Redis
熔断限流
- Polly