NetCorePal.Template 3.0.0-rc.3

工程模板

简介

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

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

前提条件

1. 安装.NET 9.0 SDK或更高版本。

   SDK下载地址： https://dot.net/download

2. 拥有Docker环境，用于自动化单元测试和集成测试。

   Docker Desktop下载地址： https://www.docker.com/products/docker-desktop/

如何使用

安装模板

dotnet new install NetCorePal.Template

安装Preview版本

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

# 例如
dotnet new install NetCorePal.Template::3.0.0-rc.2

安装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

可用参数

使用示例

# 使用默认配置（.NET 9.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

# 使用 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

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

关于 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 支持直接从包含模板的源码目录安装，无需构建和打包：

# 在项目根目录直接安装（推荐）
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

or

dotnet new install NetCorePal.Template::<VERSION>

卸载模板

dotnet new uninstall NetCorePal.Template

IDE 代码片段配置

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

Visual Studio 配置

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

cd vs-snippets
.\Install-VSSnippets.ps1

或者手动安装：

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

VS Code 配置

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

JetBrains Rider 配置

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

可用的代码片段

NetCorePal (ncp) 快捷键

Endpoint (ep) 快捷键

代码分析可视化

框架提供了强大的代码流分析和可视化功能，帮助开发者直观地理解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
  • 支持在线编辑、导出图片、生成分享链接

📖 详细文档

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

• 代码流分析文档
• 代码分析工具文档

支持特性（WIP）

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